Overview
Workflow
1. Discovery Phase
2. Analysis Phase
3. Testing Phase
4. Generation Phase
Modules
Discovery Module
Analysis Module
Testing Module
Generation Module
Examples
Analyze a Single Plugin
Test All Plugins
Full Analysis with Auto-Apply
Quick Check
Output Formats
Text Output
JSON Output
Best Practices
For Leaf Plugins
For Aggregator Makefiles
Target Naming
Integration
With Slash Commands
With CI/CD
With Development Workflow
Performance Considerations
Troubleshooting
Common Issues
Debug Mode
Contributing
License

Makefile Dogfooder Skill

Analyzes Makefiles to identify gaps in user-facing functionality, safely tests existing targets, and generates missing targets with contextually appropriate templates.

Overview

This skill provides detailed Makefile analysis and enhancement for the claude-night-market project. It helps validate that all plugins have complete, consistent, and functional Makefile targets that support common user workflows.

Workflow

1. Discovery Phase

# Find all Makefiles and extract targets
makefile_dogfooder.py --scope all --mode analyze

Verification: Run the command with --help flag to verify availability.

The discovery phase:

Recursively searches for Makefile, makefile, GNUmakefile, and *.mk files
Parses target definitions with dependencies and commands
Extracts variable assignments and include statements
Builds dependency graphs and detects plugin type (leaf vs aggregator)

2. Analysis Phase

# Analyze against best practices
makefile_dogfooder.py --mode analyze --output json

Verification: Run the command with --help flag to verify availability.

The analysis phase evaluates:

Essential targets (help, clean, .PHONY) - 20 points each
Recommended targets (test, lint, format, install, status) - 10 points each
Convenience targets (demo, dogfood, check, quick-run) - 5 points each
Anti-patterns (missing .PHONY, no error handling)
Consistency across multiple Makefiles

3. Testing Phase

# Safely test existing targets
makefile_dogfooder.py --mode test

Verification: Run pytest -v to verify tests pass.

The testing phase performs:

Syntax validation with make -n
Help target functionality checks
Variable dependency verification
Common runtime issue detection

4. Generation Phase

# Generate missing targets
makefile_dogfooder.py --mode full --apply

Verification: Run the command with --help flag to verify availability.

The generation phase creates:

Demo targets to showcase plugin functionality
Dogfood targets for self-testing
Quick-run targets for common workflows
Check-all targets for aggregator Makefiles

Modules

Discovery Module

File: modules/analysis.md

detailed file discovery algorithms
Target parsing with metadata extraction
Dependency graph construction
Inventory creation with validation

Analysis Module

File: modules/analysis.md

Target taxonomy and best practices
Anti-pattern detection rules
Consistency checking algorithms
Scoring and recommendation engine

Testing Module

File: modules/testing.md

Safe execution patterns
Target categorization (safe/conditional/risky)
Help system validation
Error detection mechanisms

Generation Module

File: modules/generation.md

Template library for common targets
Context-aware generation patterns
Interactive customization workflow
Plugin-type-specific templates

Examples

Analyze a Single Plugin

makefile_dogfooder.py --plugin abstract --mode analyze

Verification: Run the command with --help flag to verify availability.

Test All Plugins

makefile_dogfooder.py --scope plugins --mode test

Verification: Run pytest -v to verify tests pass.

Full Analysis with Auto-Apply

makefile_dogfooder.py --mode full --apply --output json

Verification: Run the command with --help flag to verify availability.

Quick Check

makefile_dogfooder.py --scope root --mode analyze

Verification: Run the command with --help flag to verify availability.

Output Formats

Text Output

Human-readable summary with scores and recommendations:

**Verification:** Run the command with `--help` flag to verify availability.
=== Makefile Dogfooding Results ===
Scope: all
Mode: full
Makefiles analyzed: 10
Issues found: 23
Recommendations made: 15

Verification: Run the command with --help flag to verify availability.

JSON Output

Machine-readable results for automation:

{
  "scope": "all",
  "mode": "full",
  "makefiles_analyzed": 10,
  "details": [
    {
      "file": "plugins/abstract/Makefile",
      "score": 100,
      "issues": 0,
      "recommendations": 0
    }
  ]
}

Verification: Run the command with --help flag to verify availability.

Best Practices

For Leaf Plugins

Always include: help, clean, test, lint
Add demo target to showcase functionality
Include dogfood target for self-testing
Use shared includes from abstract when possible

For Aggregator Makefiles

Delegate to plugin Makefiles with pattern targets
Include check-all target for detailed validation
Maintain consistent target naming across plugins
Provide helpful aggregate status information

Target Naming

Use kebab-case for target names
Include brief description with ## comment
Group related targets with prefixes (test-, dev-, docs-)
Follow alphabetical ordering for readability

Integration

With Slash Commands

The skill integrates with the /make-dogfood slash command for easy access:

/make-dogfood --scope plugins --mode full

Verification: Run the command with --help flag to verify availability.

With CI/CD

Include in GitHub Actions for automated Makefile validation:

- name: Validate Makefiles
  run: makefile_dogfooder.py --mode test --output json

Verification: Run pytest -v to verify tests pass.

With Development Workflow

Run as part of pre-commit hooks:

- repo: local
  hooks:
    - id: makefile-dogfooding
      entry: makefile_dogfooder.py
      language: system
      args: [--mode, analyze]

Verification: Run the command with --help flag to verify availability.

Performance Considerations

Large Projects: Use --scope to limit analysis scope
Quick Checks: Use --mode analyze for fastest feedback
CI Environments: Use --mode test without --apply for safe validation

Troubleshooting

Common Issues

Parse Errors: Check for complex Makefile syntax with conditionals
Timeouts: Use --mode analyze instead of --mode test for slow targets
Missing Variables: validate all referenced variables are defined
Permission Errors: Check file permissions for Makefile access

Debug Mode

Enable verbose output for troubleshooting:

makefile_dogfooder.py --mode analyze --output json | jq '.details[] | select(.issues > 0)'

Verification: Run the command with --help flag to verify availability.

Contributing

To extend the skill:

Add New Templates: Update the generation module with new target patterns
Enhance Analysis: Add new rules to the analysis module
Improve Testing: Add new test patterns to the testing module
Report Issues: Create bug reports with example Makefiles

License

MIT License - see LICENSE file for details.

makefile-dogfooder

Table of Contents