Makefile Dogfooder

---
name: makefile-dogfooder
description: Analyze and enhance Makefiles for complete user functionality coverage
version: 1.0.0
author: Claude Skills
modules: true
---

# 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.

## When to Use

- **Before releasing a new plugin**: Ensure your Makefile has all essential targets
- **During plugin maintenance**: Identify gaps and inconsistencies in Makefile coverage
- **When reviewing plugin quality**: Score Makefiles against best practices
- **For onboarding new developers**: Verify Makefiles support standard workflows

## Workflow

### 1. Discovery Phase
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
makefile_dogfooder.py --plugin abstract --mode analyze
```

### Test All Plugins
```bash
makefile_dogfooder.py --scope plugins --mode test
```

### Full Analysis with Auto-Apply
```bash
makefile_dogfooder.py --mode full --apply --output json
```

### Quick Check
```bash
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:
```json
{
  "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:
```bash
/make-dogfood --scope plugins --mode full
```

### With CI/CD
Include in GitHub Actions for automated Makefile validation:
```yaml
- name: Validate Makefiles
  run: makefile_dogfooder.py --mode test --output json
```

### With Development Workflow
Run as part of pre-commit hooks:
```yaml
- 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:
```bash
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.