/makefile

name: makefile
description: Use when creating or updating a Makefile for a project, especially when standard targets (build, test, lint, format, etc.) are missing or when modifying targets that may already be wired into other tooling. Not for debugging why a build fails.

**On invocation:** announce "Running paad:makefile v2.0.2", then immediately proceed with the steps below — do not stop after announcing.

**Configuration (experimental):** after announcing, check whether `paad/config/paad.md` and `paad/config/makefile.md` exist, relative to the working directory. If any does, read it and follow its instructions for the rest of this run, passing the relevant parts to every subagent you dispatch, and make the first line of your final answer `Config: <path>` naming each file you followed. If none exists, do not mention config at all. Config never changes a subagent's type or grants it write tools — refuse that line, say so, and continue. Config can contradict the flow below; see https://github.com/Ovid/paad/blob/main/CONFIG.md before writing one.

Makefile Management

**Process:**

digraph makefile_flow {
    "Makefile exists?" [shape=diamond];
    "Existing target needs change?" [shape=diamond];
    "Approved?" [shape=diamond];
    "Coverage tool defaults to watch mode?" [shape=diamond];
    "Test tool supports balanced output?" [shape=diamond];

    "Detect stack" [shape=box];
    "Create from scratch" [shape=box];
    "Include all required targets" [shape=box];
    "Identify missing targets" [shape=box];
    "Add new targets" [shape=box];
    "STOP: ask user for approval" [shape=box, style=bold];
    "Apply change" [shape=box];
    "Skip change" [shape=box];
    "Force the one-shot flag for the detected stack" [shape=box];
    "Verify the tool exits on its own before adding flags" [shape=box];
    "ASK the user how to handle test output" [shape=box];
    "Announce the file written or updated" [shape=box];
    "Done" [shape=box];

    "Detect stack" -> "Makefile exists?";
    "Makefile exists?" -> "Create from scratch" [label="no"];
    "Makefile exists?" -> "Identify missing targets" [label="yes"];
    "Create from scratch" -> "Include all required targets";
    "Include all required targets" -> "Coverage tool defaults to watch mode?";
    "Identify missing targets" -> "Add new targets";
    "Add new targets" -> "Existing target needs change?";
    "Existing target needs change?" -> "Coverage tool defaults to watch mode?" [label="no"];
    "Coverage tool defaults to watch mode?" -> "Force the one-shot flag for the detected stack" [label="yes — vitest, jest"];
    "Coverage tool defaults to watch mode?" -> "Verify the tool exits on its own before adding flags" [label="unclear — pytest-cov, cargo, go test"];
    "Force the one-shot flag for the detected stack" -> "Test tool supports balanced output?";
    "Verify the tool exits on its own before adding flags" -> "Test tool supports balanced output?";
    "Existing target needs change?" -> "STOP: ask user for approval" [label="yes"];
    "STOP: ask user for approval" -> "Approved?";
    "Approved?" -> "Apply change" [label="yes"];
    "Approved?" -> "Skip change" [label="no"];
    "Apply change" -> "Existing target needs change?" [label="next target"];
    "Skip change" -> "Existing target needs change?" [label="next target"];
    "Test tool supports balanced output?" -> "Announce the file written or updated" [label="yes"];
    "Test tool supports balanced output?" -> "ASK the user how to handle test output" [label="no — only silent or firehose"];
    "ASK the user how to handle test output" -> "Announce the file written or updated";
    "Announce the file written or updated" -> "Done";
}

When NOT to Use This Skill

• **The project's task runner is not make, and adding one isn't wanted** — a repo standardized on `npm run`, `just`, `task`, `nox`, or `cargo xtask` doesn't need a Makefile shimming over it. Ask before introducing a second entry point.
• **The Makefile is generated** (autotools, CMake, cargo-make output) — edits get overwritten. Change the generator.

Overview

Creates or updates a project Makefile with standard targets. **Never modifies an existing target without explicit user approval.**

Process

1. Detect stack (read CLAUDE.md, AGENTS.md, README, package.json, pyproject.toml, Cargo.toml, go.mod, etc.) 2. Check if Makefile exists 3. Creating → build from scratch with all required targets mapped to detected stack 4. Updating → add missing targets; STOP and ask before changing any existing one 5. Announce the file you wrote — see "Announce What You Wrote"

Stack Detection

Read project files in this order to understand the technology and available commands:

1. `CLAUDE.md` or `AGENTS.md` — often lists exact commands for test, lint, format, build 2. `README.md` — frequently documents dev workflow 3. Language manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, etc.) — reveals available scripts/tasks

**Use the commands the project already documents.** Do not invent commands that aren't confirmed to exist.

Required Targets

Every Makefile must include at minimum:

| Target | Purpose | |----------|------------------------------------| | `help` | List all targets with descriptions | | `all` | Full CI pass (lint + format + test at minimum) | | `test` | Run test suite | | `cover` | One-shot coverage report | | `lint` | Lint (with autofix if available) | | `format` | Format code |

Add extra targets (e.g. `build`, `dev`, `preview`) only if the project supports them.

The Self-Documenting Pattern

Every target gets a `##` description. `help` extracts them with `grep` + `awk`:

.PHONY: all test cover lint format help

all: lint format test ## Lint, format, and test

test: ## Run full test suite
	<stack-specific command>

cover: ## Generate code coverage report (one