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 comprehensive Makefile analysis and enhancement for the claude-night-market project. It helps ensure 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

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

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

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

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/discovery.md

• Comprehensive 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

Test All Plugins

makefile_dogfooder.py --scope plugins --mode test

Full Analysis with Auto-Apply

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

Quick Check

makefile_dogfooder.py --scope root --mode analyze

Output Formats

Text Output

Human-readable summary with scores and recommendations:

=== Makefile Dogfooding Results ===
Scope: all
Mode: full
Makefiles analyzed: 10
Issues found: 23
Recommendations made: 15

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
    }
  ]
}

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 comprehensive 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

With CI/CD

Include in GitHub Actions for automated Makefile validation:

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

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]

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

1. Parse Errors: Check for complex Makefile syntax with conditionals
2. Timeouts: Use --mode analyze instead of --mode test for slow targets
3. Missing Variables: Ensure all referenced variables are defined
4. 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)'

Contributing

To extend the skill:

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

License

MIT License - see LICENSE file for details.