Menu
Reference for modifying the Makefile, not for running make targets
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Automated quality check loops with escalation and fix sub-agents
JSON-based end-to-end test format, runner, and mock provider
Jujutsu (jj) skill for the ikigai project
How to write effective Ralph goals for Ikigai-driven workflows
Create and manage Ralph goals from Ikigai using the real ralph-pipeline scripts
Create repositories using the real ralph-pipeline repo-create script
| name | makefile |
| description | Reference for modifying the Makefile, not for running make targets |
Reference documentation for making changes to the Makefile itself. This is not a guide for running make targets.
Autonomous agents must never run make directly. Use the check-* scripts (e.g. check-compile, check-unit, check-quality) instead.
FUNDAMENTAL REQUIREMENT: All check targets must have consistent, minimal output.
Output format:
The 10 check targets:
check-compile - Compile all .c files to .o filescheck-link - Link all binaries (main, tests, tools)check-filesize - Verify files are under size limitscheck-unit - Run unit testscheck-integration - Run integration testscheck-complexity - Check cyclomatic complexity and nesting depthcheck-sanitize - Run tests with AddressSanitizer and UndefinedBehaviorSanitizercheck-tsan - Run tests with ThreadSanitizercheck-valgrind - Run tests under Valgrind Memcheckcheck-helgrind - Run tests under Valgrind HelgrindAll checks must behave identically in output format.
make all - Build the ikigai client binary with default debug configuration.make release - Clean and rebuild the client in release mode with optimizations.make clean - Remove all build artifacts, coverage data, reports, and distribution packages.make check-compile - Compile all .c files (src + tests) to .o files. Emits 🟢/🔴 per file.make check-compile FILE=src/foo.c - Compile only the specified file + dependencies.make check-link - Link all binaries (client, tests, tools). Emits 🟢/🔴 per binary.make check-link FILE=build/debug/tests/unit/foo_test - Link only the specified binary.make install - Install the ikigai binary and config files to PREFIX (default /usr/local).make uninstall - Remove installed binary and configuration files from the system.make install-deps - Install build dependencies using the system package manager.make check - Build and run all tests in parallel (unit and integration).make check TEST=name - Build and run a single test matching the specified name.make check-unit - Build and run only unit tests in parallel.make check-integration - Build and run only integration and database tests.make verify-mocks - Verify OpenAI mock fixtures against real API responses.make verify-mocks-anthropic - Verify Anthropic mock fixtures against real API responses.make verify-mocks-google - Verify Google mock fixtures against real API responses.make verify-mocks-all - Verify all provider mock fixtures against real APIs.make verify-credentials - Validate API keys in ~/.config/ikigai/credentials.json.make vcr-record-openai - Re-record OpenAI VCR fixtures with real API calls.make vcr-record-anthropic - Re-record Anthropic VCR fixtures with real API calls.make vcr-record-google - Re-record Google VCR fixtures with real API calls.make vcr-record-all - Re-record all provider VCR fixtures.make check-sanitize - Run all tests with AddressSanitizer and UndefinedBehaviorSanitizer.make check-valgrind - Run all tests under Valgrind Memcheck for memory leak detection.make check-helgrind - Run all tests under Valgrind Helgrind for thread error detection.make check-tsan - Run all tests with ThreadSanitizer for race condition detection.make check-dynamic - Run all dynamic analysis checks sequentially (or parallel with PARALLEL=1).make check-coverage - Generate code coverage report and enforce coverage thresholds.make coverage-map - Generate source file to test mapping for targeted coverage runs.make lint - Run all lint checks (complexity and filesize).make check-complexity - Check cyclomatic complexity and nesting depth against thresholds.make check-filesize - Verify all source and documentation files are below size limits.make ci - Run complete CI pipeline (lint, coverage, all tests, all dynamic analysis).make fmt - Format all source code using uncrustify with project style guide.make tags - Generate ctags index for source code navigation.make cloc - Count lines of code in source, tests, and Makefile.make dist - Create source distribution tarball for packaging.make distro-images - Build Docker images for all supported distributions.make distro-images-clean - Remove all Docker images for supported distributions.make distro-clean - Clean build artifacts using Docker container.make distro-check - Run full CI checks on all supported distributions via Docker.make distro-package - Build distribution packages (deb, rpm) for all supported distributions.make help - Display detailed help for all available targets and build modes.make clean-test-runs - Remove test run sentinel files used for parallel execution.| Mode | Flags | Purpose |
|---|---|---|
BUILD=debug | -O0 -g3 -DDEBUG | Default build with full debug symbols and no optimization |
BUILD=release | -O2 -g -DNDEBUG -D_FORTIFY_SOURCE=2 | Optimized production build with security hardening |
BUILD=sanitize | -O0 -g3 -fsanitize=address,undefined | Debug build with address and undefined behavior sanitizers |
BUILD=tsan | -O0 -g3 -fsanitize=thread | Debug build with thread sanitizer for race detection |
BUILD=valgrind | -O0 -g3 -fno-omit-frame-pointer | Debug build optimized for Valgrind analysis |
# Development workflow
make clean && make all # Clean build in debug mode
make check # Run all tests
make fmt # Format code before commit
# Single test execution
make check TEST=config_test # Run only config_test
# Quality assurance
make lint # Check complexity and file sizes
make check-coverage # Generate coverage report
make check-dynamic # Run all sanitizers and Valgrind
# Release workflow
make release # Build optimized release binary
make ci # Run full CI pipeline
# Distribution workflow
make dist # Create source tarball
make distro-images # Build Docker images
make distro-package # Build deb/rpm packages
# Custom builds
make all BUILD=release # Build in release mode
make check BUILD=sanitize # Run tests with sanitizers
make check-coverage COVERAGE_THRESHOLD=95 # Require 95% coverage
# Distribution testing
make distro-check DISTROS="debian" # Test only on Debian
make distro-package DISTROS="fedora ubuntu" # Build packages for specific distros
# Parallel execution
make -j8 check # Run tests with 8 parallel jobs
make check-dynamic PARALLEL=1 # Run sanitizers in parallel
# VCR fixture recording
VCR_RECORD=1 make check-unit # Re-record fixtures during test run
make vcr-record-openai # Re-record all OpenAI fixtures
tool_name_tool: libexec/ikigai/tool-name-tool
libexec/ikigai/tool-name-tool: src/tools/tool_name/main.c $(TOOL_COMMON_SRCS) | libexec/ikigai
@$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ -ltalloc && echo "🔗 $@" || (echo "🔴 $@" && exit 1)
Critical: $(LDFLAGS) must come before -o $@ $^, not after. Libraries go at the end.
CRITICAL: Only two file endings are allowed in the tests/ directory:
*_test.c - Test files that build into test binaries*_helper.c - Helper files used by tests (stubs, mocks, utilities)Any other naming pattern is invalid and must be renamed to match one of these patterns.