Analyze project and generate or enhance build automation file (Makefile, Taskfile.yml, Justfile, Magefile.go). If a build file already exists, improves it by adding missing targets and best practices. Use when user says "generate makefile", "create taskfile", "add justfile", "setup mage", or "build automation".
Generate or enhance a build automation file for any project. Supports Makefile, Taskfile.yml, Justfile, and Magefile.go.
Two modes:
Read the project description if available:
Read .ai-factory/DESCRIPTION.md
Store the project context (tech stack, framework, architecture) for use in later steps. If the file doesn't exist, that's fine — we'll detect everything in Step 2.
Read .ai-factory/skill-context/aif-build-automation/SKILL.md — MANDATORY if the file exists.
This file contains project-specific rules accumulated by from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
$aif-evolveHow to apply skill-context rules:
Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.
Before anything else, check if the project already has build automation:
Glob: Makefile, makefile, GNUmakefile, Taskfile.yml, Taskfile.yaml, taskfile.yml, justfile, Justfile, .justfile, magefile.go, magefiles/*.go
Build a list of EXISTING_FILES from the results.
Mode A — Enhance Existing (if EXISTING_FILES is not empty):
MODE = "enhance"TARGET_TOOL automatically from the detected file (Makefile → makefile, Taskfile.yml → taskfile, etc.)$ARGUMENTS specifies one, use the argument to pick which one to enhanceAskUserQuestion: This project has multiple build files. Which one should I improve?
Options (dynamic, based on what exists):
1. Makefile — Enhance the existing Makefile
2. Taskfile.yml — Enhance the existing Taskfile
...
EXISTING_CONTENTMode B — Generate New (if EXISTING_FILES is empty):
MODE = "generate"$ARGUMENTS to determine tool:| Argument | Tool | Output File |
|---|---|---|
makefile or make | GNU Make | Makefile |
taskfile or task | Taskfile | Taskfile.yml |
justfile or just | Just | justfile |
mage or magefile | Mage | magefile.go |
$ARGUMENTS is empty or doesn't match, ask the user interactively:AskUserQuestion: Which build automation tool do you want to generate?
Options:
1. Makefile — GNU Make (universal, no install needed)
2. Taskfile.yml — Task runner (YAML, modern, cross-platform)
3. justfile — Just command runner (simple, fast, ergonomic)
4. magefile.go — Mage (Go-native, type-safe, no shell scripts)
Store the chosen tool as TARGET_TOOL.
Detect the project profile by scanning the repository. Run these checks using Glob and Grep:
Check for these files (first match wins):
| File | Language |
|---|---|
go.mod | Go |
package.json | Node.js / JavaScript / TypeScript |
pyproject.toml or setup.py or setup.cfg | Python |
Cargo.toml | Rust |
composer.json | PHP |
Gemfile | Ruby |
build.gradle or pom.xml | Java/Kotlin |
*.csproj or *.sln | C# / .NET |
Check lock files:
| File | Package Manager |
|---|---|
bun.lockb | bun |
pnpm-lock.yaml | pnpm |
yarn.lock | yarn |
package-lock.json | npm |
poetry.lock | poetry |
uv.lock | uv |
Pipfile.lock | pipenv |
For Node.js projects, check package.json dependencies for:
next → Next.jsnuxt → Nuxt@remix-run/node → Remixexpress → Expressfastify → Fastifyhono → Hono@nestjs/core → NestJSFor Python projects, check pyproject.toml or imports for:
fastapi → FastAPIdjango → Djangoflask → FlaskFor PHP projects, check composer.json require for:
laravel/framework → Laravelsymfony/framework-bundle → Symfonyslim/slim → Slimcakephp/cakephp → CakePHPFor Go projects, check go.mod for:
gin-gonic/gin → Ginlabstack/echo → Echogofiber/fiber → Fibergo-chi/chi → ChiGlob: Dockerfile, Dockerfile.*, docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml, .dockerignore
If any exist, set HAS_DOCKER=true and perform a deeper analysis:
Read the Dockerfile(s) to detect:
dev / prod stages) → DOCKER_MULTISTAGE=trueDOCKER_PORTS (e.g., 3000, 8080)DOCKER_BASE (e.g., node:20-alpine, golang:1.22)Read docker-compose / compose file to detect:
DOCKER_SERVICES (e.g., app, db, redis, worker)dev, production, testDOCKER_DEPSStore as DOCKER_PROFILE:
has_compose: booleanhas_multistage: booleanservices: list of service namesdeps: list of infrastructure services (db, cache, queue)ports: exposed portshas_dev_stage: boolean (Dockerfile has a dev or development stage)Glob: .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile, .travis.yml
Note which CI system is in use.
Search for migration tools:
Grep: prisma|drizzle|knex|typeorm|sequelize|alembic|django.*migrate|goose|migrate|atlas|sqlx
Check for:
prisma/schema.prisma → Prismadrizzle.config.ts → Drizzlealembic/ directory → Alembicmigrations/ directory → Generic migrations| Language | Check For |
|---|---|
| Node.js | jest, vitest, mocha, ava in package.json |
| Python | pytest in pyproject.toml/requirements, unittest imports |
| Go | Go has built-in testing; check for testify in go.mod |
| Rust | Built-in; check for integration test directory tests/ |
Glob: .eslintrc*, eslint.config.*, .prettierrc*, biome.json, .golangci.yml, .golangci.yaml
Grep in pyproject.toml: ruff|black|flake8|pylint|isort
Glob: turbo.json, nx.json, lerna.json, pnpm-workspace.yaml
Build a PROJECT_PROFILE object with:
language: primary languagepackage_manager: detected PMframework: detected framework (if any)has_docker: booleandocker_profile: DOCKER_PROFILE object (if has_docker)ci_system: detected CI (if any)has_migrations: boolean + tool nametest_framework: detected test runnerlinters: list of detected lintersis_monorepo: booleanhas_dev_server: boolean (framework with dev server)Read the best practices reference for the chosen tool:
Read skills/build-automation/references/BEST-PRACTICES.md
Focus on the section matching TARGET_TOOL:
Also read the "Cross-Cutting Concerns" section for standard targets.
Pick the closest matching template based on language + TARGET_TOOL:
| Tool | Go | Node.js | Python | PHP | Other |
|---|---|---|---|---|---|
| Makefile | makefile-go.mk | makefile-node.mk | makefile-python.mk | makefile-php.mk | Use closest match |
| Taskfile | taskfile-go.yml | taskfile-node.yml | taskfile-python.yml | taskfile-php.yml | Use closest match |
| Justfile | justfile-go | justfile-node | justfile-python | justfile-php | Use closest match |
| Magefile | magefile-basic.go | magefile-full.go | magefile-full.go | N/A (use Makefile) | magefile-basic.go |
For Magefile: use magefile-full.go if HAS_DOCKER or has_migrations is true, otherwise magefile-basic.go.
For PHP + Magefile: Mage is Go-specific and not applicable to PHP projects. If the user explicitly requested mage for a PHP project, explain this and suggest Makefile as the closest alternative (universal, no install needed). Ask via AskUserQuestion whether to proceed with Makefile instead.
Read the selected template:
Read skills/build-automation/templates/<selected-template>
Using the PROJECT_PROFILE, best practices, and template as reference, generate a customized build file from scratch.
has_dockerhas_migrations (use correct migration tool)has_docker, generate a dedicated Docker section (see below)When has_docker is true, generate two layers of commands:
Layer 1 — Container lifecycle (always when Docker detected):
| Target | Purpose |
|---|---|
docker-build or docker:build | Build the Docker image |
docker-run or docker:run | Run the container |
docker-stop or docker:stop | Stop running containers |
docker-logs or docker:logs | Tail container logs |
docker-push or docker:push | Push image to registry |
docker-clean or docker:clean | Remove images and stopped containers |
Layer 2 — Dev vs Production separation (when compose or multistage detected):
##@ Docker — Development
docker-dev: ## Start all services in dev mode (with hot reload, mounted volumes)
docker-dev-build: ## Rebuild dev containers
docker-dev-down: ## Stop dev environment and remove volumes
##@ Docker — Production
docker-prod-build: ## Build production image (optimized, multi-stage)
docker-prod-run: ## Run production container locally for testing
docker-prod-push: ## Push production image to registry
Generation logic:
has_compose → use docker compose commands (not docker-compose)--profile dev / --profile productionhas_multistage → use --target dev for dev builds, no target (or --target production) for proddocker_profile.deps exist (db, redis, etc.) → add infra-up / infra-down targets to start/stop only infrastructure services without the appdocker-dev should run docker compose up with correct profile/servicesdocker-dev should run docker build --target dev + docker run with volume mountsLayer 3 — Container-based commands (mirror host commands via container):
When the project is Docker-based, also generate container-exec variants so that users who run everything in Docker can use the same targets:
# Run tests inside the container
docker-test: ## Run tests inside the Docker container
docker compose exec app [test command]
# Run linter inside the container
docker-lint: ## Run linter inside the Docker container
docker compose exec app [lint command]
# Open shell in the container
docker-shell: ## Open a shell inside the running container
docker compose exec app sh
Only generate docker-* exec variants if the project appears to be Docker-first (compose file mounts source code as volumes, or no local language runtime setup is apparent).
go.mod, package.json, or directory namesrc/, app/, cmd/)next dev, uvicorn --reload, air)When MODE = "enhance", do NOT replace the file from scratch. Instead, analyze it and improve it surgically.
Compare EXISTING_CONTENT against the PROJECT_PROFILE and best practices. Build a gap analysis:
Missing preamble/config — Check if the file has the recommended preamble:
SHELL := bash, .ONESHELL, .SHELLFLAGS, .DELETE_ON_ERROR, MAKEFLAGSversion: '3', output:, dotenv:set shell, set dotenv-load, set export//go:build mage, proper importsMissing standard targets — Check which of these are absent:
help / default (self-documenting)build, test, lint, clean, dev, fmtci (aggregate target)Missing project-specific targets — Based on PROJECT_PROFILE, check for:
has_docker but no docker targets in file)has_migrations but no db targets)Quality issues — Check for anti-patterns from best practices:
.PHONY declarations (Makefile)Build a list of specific changes to make:
CHANGES = [
{ type: "add_preamble", detail: "Add .SHELLFLAGS and .DELETE_ON_ERROR" },
{ type: "add_target", name: "docker-build", detail: "Dockerfile detected but no docker target" },
{ type: "add_target", name: "help", detail: "No self-documenting help target" },
{ type: "fix_quality", detail: "Add ## comments to 3 targets missing descriptions" },
{ type: "add_variable", detail: "Add VERSION/COMMIT detection via git" },
...
]
##@ sections, add to matching section; if no sections, append logically)Before writing the file, verify:
.PHONY declarations for all non-file targets (Makefile only)Mode B (Generate New):
Write the generated content using the Write tool:
| Tool | Output Path |
|---|---|
| Makefile | Makefile |
| Taskfile | Taskfile.yml |
| Justfile | justfile |
| Magefile | magefile.go |
Mode A (Enhance Existing):
Write the enhanced content to the same path where the existing file was found (preserving the original filename casing and location). The file is updated in-place — no need to ask about overwriting since we're improving, not replacing.
Display summary using format from references/SUMMARY-FORMAT.md. Shows targets table, project profile used, and quick start command for Mode B (generate), or what changed + new/existing targets for Mode A (enhance). Include installation hints if the tool requires setup.
After writing the build file, integrate quick commands into project docs.
For detailed integration procedures (README, AGENTS.md, existing markdown) → read references/DOC-INTEGRATION.md
Brief: scan for existing command sections, update or append quick reference, suggest AGENTS.md creation if missing.
Makefile, Taskfile.yml, justfile, magefile.go).AGENTS.md when directly tied to the generated build workflow.config.yaml.