Initial commit
This commit is contained in:
Zhongwei Li
670
skills/meta-automation-architect/examples/EXAMPLE_PYTHON_CLI.md
Normal file
670
skills/meta-automation-architect/examples/EXAMPLE_PYTHON_CLI.md
Normal file
@@ -0,0 +1,670 @@
|
||||
# Example: Python CLI Tool Automation
|
||||
|
||||
This example shows what the meta-automation-architect generates for a Python command-line tool project.
|
||||
|
||||
## Project Context
|
||||
|
||||
- **Type**: CLI Tool
|
||||
- **Stack**: Python 3.11, Click framework, SQLite
|
||||
- **Team Size**: Solo developer
|
||||
- **Pain Points**: Documentation, testing, dependency management
|
||||
- **Priority**: User documentation and testing
|
||||
|
||||
## User Conversation
|
||||
|
||||
```
|
||||
User: "Create automation for my Python CLI project"
|
||||
|
||||
Meta-Skill: Analyzing project...
|
||||
- Detected: CLI Tool (87% confidence)
|
||||
- Found cli.py with Click decorators
|
||||
- Found setup.py with console_scripts entry point
|
||||
- Found requirements.txt with CLI dependencies
|
||||
- Found README.md but missing detailed docs
|
||||
|
||||
Meta-Skill: What are your main pain points?
|
||||
Options:
|
||||
- Low test coverage (RECOMMENDED: 8 test files for 42 modules)
|
||||
- Missing documentation (RECOMMENDED: No docs/ directory)
|
||||
- Dependency issues
|
||||
- Release process
|
||||
|
||||
User: [Selects: Low test coverage, Missing documentation]
|
||||
|
||||
Meta-Skill: How many agents should we create?
|
||||
- Few (2-3): Basic analysis (RECOMMENDED for solo projects)
|
||||
- Moderate (4-6): Multi-domain coverage
|
||||
- Many (7+): Comprehensive automation
|
||||
|
||||
User: [Selects: Few]
|
||||
|
||||
Meta-Skill: Generating automation system...
|
||||
Session ID: b2c3d4e5-f6a7-8901-bcde-f23456789012
|
||||
```
|
||||
|
||||
## Generated Automation System
|
||||
|
||||
### 1. Custom Subagents (4)
|
||||
|
||||
All agents created in `.claude/agents/`:
|
||||
|
||||
#### Analysis Agents (Run in Parallel)
|
||||
|
||||
**code-quality-analyzer.md**
|
||||
- Checks PEP 8 compliance
|
||||
- Analyzes function complexity
|
||||
- Identifies code duplication
|
||||
- Reviews error handling
|
||||
|
||||
**testing-analyzer.md**
|
||||
- Measures test coverage
|
||||
- Identifies untested CLI commands
|
||||
- Reviews test patterns
|
||||
- Checks for integration tests
|
||||
|
||||
#### Implementation Agents
|
||||
|
||||
**skill-generator.md**
|
||||
- Creates custom skills for Python patterns
|
||||
- Generated: `docstring-generator`, `cli-test-helper`
|
||||
|
||||
**command-generator.md**
|
||||
- Creates commands for Python workflows
|
||||
- Generated: `/test-cov`, `/release-prep`
|
||||
|
||||
### 2. Custom Skills (2)
|
||||
|
||||
**`.claude/skills/docstring-generator/SKILL.md`**
|
||||
```markdown
|
||||
---
|
||||
name: docstring-generator
|
||||
description: Generates comprehensive docstrings for Python functions and modules
|
||||
allowed-tools: ["Read", "Write", "Grep", "Glob"]
|
||||
---
|
||||
|
||||
# Docstring Generator
|
||||
|
||||
Automatically generates NumPy-style docstrings for Python code.
|
||||
|
||||
## When This Activates
|
||||
|
||||
- User asks to "add documentation" to Python files
|
||||
- User requests "docstrings" for functions
|
||||
- User says "document this module"
|
||||
|
||||
## Process
|
||||
|
||||
1. Scan Python files for functions/classes without docstrings
|
||||
2. Analyze function signatures, type hints, and logic
|
||||
3. Generate NumPy-style docstrings with:
|
||||
- Brief description
|
||||
- Parameters with types
|
||||
- Returns with type
|
||||
- Raises (exceptions)
|
||||
- Examples
|
||||
4. Insert docstrings into code
|
||||
5. Validate with pydocstyle
|
||||
|
||||
## Example
|
||||
|
||||
**Input:**
|
||||
```python
|
||||
def parse_config(path, validate=True):
|
||||
with open(path) as f:
|
||||
config = json.load(f)
|
||||
if validate:
|
||||
validate_config(config)
|
||||
return config
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```python
|
||||
def parse_config(path: str, validate: bool = True) -> dict:
|
||||
"""
|
||||
Parse configuration from JSON file.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
path : str
|
||||
Path to configuration file
|
||||
validate : bool, optional
|
||||
Whether to validate configuration (default: True)
|
||||
|
||||
Returns
|
||||
-------
|
||||
dict
|
||||
Parsed configuration dictionary
|
||||
|
||||
Raises
|
||||
------
|
||||
FileNotFoundError
|
||||
If configuration file doesn't exist
|
||||
ValidationError
|
||||
If configuration is invalid and validate=True
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> config = parse_config('config.json')
|
||||
>>> config['database']['host']
|
||||
'localhost'
|
||||
"""
|
||||
with open(path) as f:
|
||||
config = json.load(f)
|
||||
if validate:
|
||||
validate_config(config)
|
||||
return config
|
||||
```
|
||||
|
||||
[... detailed implementation ...]
|
||||
```
|
||||
|
||||
**`.claude/skills/cli-test-helper/SKILL.md`**
|
||||
```markdown
|
||||
---
|
||||
name: cli-test-helper
|
||||
description: Generates tests for Click CLI commands with fixtures
|
||||
allowed-tools: ["Read", "Write", "Bash", "Grep"]
|
||||
---
|
||||
|
||||
# CLI Test Helper
|
||||
|
||||
Automatically generates pytest tests for Click commands.
|
||||
|
||||
## When This Activates
|
||||
|
||||
- User implements new CLI command
|
||||
- User requests "test this command"
|
||||
- User says "add CLI tests"
|
||||
|
||||
## Process
|
||||
|
||||
1. Identify Click commands in code
|
||||
2. Extract command parameters, options, flags
|
||||
3. Generate pytest tests with:
|
||||
- CliRunner fixtures
|
||||
- Success case tests
|
||||
- Error case tests
|
||||
- Edge case tests
|
||||
- Output validation
|
||||
4. Create test fixtures for complex inputs
|
||||
5. Run tests to verify
|
||||
|
||||
## Example
|
||||
|
||||
**CLI Command:**
|
||||
```python
|
||||
@click.command()
|
||||
@click.option('--name', required=True, help='User name')
|
||||
@click.option('--email', help='User email')
|
||||
@click.option('--verbose', is_flag=True)
|
||||
def create_user(name, email, verbose):
|
||||
"""Create a new user."""
|
||||
user = User(name=name, email=email)
|
||||
db.save(user)
|
||||
if verbose:
|
||||
click.echo(f"Created user: {user}")
|
||||
else:
|
||||
click.echo(user.id)
|
||||
```
|
||||
|
||||
**Generated Test:**
|
||||
```python
|
||||
import pytest
|
||||
from click.testing import CliRunner
|
||||
from myapp.cli import create_user
|
||||
|
||||
@pytest.fixture
|
||||
def runner():
|
||||
return CliRunner()
|
||||
|
||||
def test_create_user_success(runner):
|
||||
"""Test successful user creation."""
|
||||
result = runner.invoke(create_user, ['--name', 'Alice'])
|
||||
assert result.exit_code == 0
|
||||
assert 'user-' in result.output
|
||||
|
||||
def test_create_user_with_email(runner):
|
||||
"""Test user creation with email."""
|
||||
result = runner.invoke(create_user, [
|
||||
'--name', 'Alice',
|
||||
'--email', 'alice@example.com'
|
||||
])
|
||||
assert result.exit_code == 0
|
||||
|
||||
def test_create_user_verbose(runner):
|
||||
"""Test verbose output."""
|
||||
result = runner.invoke(create_user, [
|
||||
'--name', 'Alice',
|
||||
'--verbose'
|
||||
])
|
||||
assert result.exit_code == 0
|
||||
assert 'Created user:' in result.output
|
||||
|
||||
def test_create_user_missing_name(runner):
|
||||
"""Test error when name is missing."""
|
||||
result = runner.invoke(create_user, [])
|
||||
assert result.exit_code != 0
|
||||
assert 'Missing option' in result.output
|
||||
```
|
||||
|
||||
[... detailed implementation ...]
|
||||
```
|
||||
|
||||
### 3. Custom Commands (2)
|
||||
|
||||
**`.claude/commands/test-cov.md`**
|
||||
```markdown
|
||||
---
|
||||
description: Run tests with coverage report
|
||||
allowed-tools: ["Bash", "Read"]
|
||||
---
|
||||
|
||||
# Test Coverage Command
|
||||
|
||||
Runs pytest with coverage and generates detailed report.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/test-cov # Full coverage
|
||||
/test-cov tests/unit # Specific directory
|
||||
/test-cov --html # Generate HTML report
|
||||
```
|
||||
|
||||
## What This Does
|
||||
|
||||
1. **Run Tests with Coverage**
|
||||
```bash
|
||||
pytest --cov=src --cov-report=term-missing $ARGUMENTS
|
||||
```
|
||||
|
||||
2. **Generate Report**
|
||||
- Terminal: Coverage percentage by module
|
||||
- Missing lines highlighted
|
||||
- HTML report (if --html flag)
|
||||
|
||||
3. **Check Thresholds**
|
||||
- Warn if coverage < 80%
|
||||
- Error if coverage < 60%
|
||||
|
||||
4. **Identify Gaps**
|
||||
- List untested files
|
||||
- Highlight critical paths without tests
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
---------- coverage: platform darwin, python 3.11.5 -----------
|
||||
Name Stmts Miss Cover Missing
|
||||
-------------------------------------------------------
|
||||
src/__init__.py 2 0 100%
|
||||
src/cli.py 145 23 84% 67-73, 89-92
|
||||
src/config.py 34 0 100%
|
||||
src/database.py 89 45 49% 23-67, 78-89
|
||||
src/utils.py 23 2 91% 45-46
|
||||
-------------------------------------------------------
|
||||
TOTAL 293 70 76%
|
||||
|
||||
⚠️ Coverage below 80% target
|
||||
❌ database.py has only 49% coverage (critical module!)
|
||||
|
||||
Suggestions:
|
||||
- Add integration tests for database.py
|
||||
- Test error paths in cli.py lines 67-73
|
||||
```
|
||||
|
||||
[... detailed implementation ...]
|
||||
```
|
||||
|
||||
**`.claude/commands/release-prep.md`**
|
||||
```markdown
|
||||
---
|
||||
description: Prepare project for release (version bump, tests, build)
|
||||
allowed-tools: ["Bash", "Read", "Write"]
|
||||
---
|
||||
|
||||
# Release Preparation
|
||||
|
||||
Automates release preparation checklist.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/release-prep # Interactive mode
|
||||
/release-prep patch # Auto-bump patch version
|
||||
/release-prep minor # Auto-bump minor version
|
||||
/release-prep major # Auto-bump major version
|
||||
```
|
||||
|
||||
## Process
|
||||
|
||||
1. **Run Full Test Suite**
|
||||
```bash
|
||||
pytest -v
|
||||
```
|
||||
|
||||
2. **Check Coverage**
|
||||
```bash
|
||||
pytest --cov=src --cov-report=term
|
||||
```
|
||||
|
||||
3. **Lint Code**
|
||||
```bash
|
||||
ruff check src/
|
||||
mypy src/
|
||||
```
|
||||
|
||||
4. **Bump Version**
|
||||
- Update version in setup.py, __version__.py
|
||||
- Update CHANGELOG.md
|
||||
- Create git tag
|
||||
|
||||
5. **Build Distributions**
|
||||
```bash
|
||||
python -m build
|
||||
```
|
||||
|
||||
6. **Test Installation**
|
||||
```bash
|
||||
pip install dist/*.whl
|
||||
```
|
||||
|
||||
7. **Generate Release Notes**
|
||||
- Extract commits since last tag
|
||||
- Categorize changes (features, fixes, breaking)
|
||||
- Write to RELEASE_NOTES.md
|
||||
|
||||
8. **Checklist Output**
|
||||
```
|
||||
✅ All tests pass (147 passed)
|
||||
✅ Coverage: 87%
|
||||
✅ Linting: No issues
|
||||
✅ Version bumped: 1.2.3 → 1.2.4
|
||||
✅ CHANGELOG.md updated
|
||||
✅ Distribution built
|
||||
✅ Installation tested
|
||||
✅ Release notes generated
|
||||
|
||||
Ready to release! Next steps:
|
||||
1. Review RELEASE_NOTES.md
|
||||
2. git push --tags
|
||||
3. twine upload dist/*
|
||||
```
|
||||
|
||||
[... detailed implementation ...]
|
||||
```
|
||||
|
||||
### 4. Hooks (1)
|
||||
|
||||
**`.claude/hooks/lint_python.py`**
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Python Linting Hook
|
||||
Type: PostToolUse
|
||||
Automatically lints Python files after edits
|
||||
"""
|
||||
|
||||
import sys
|
||||
import json
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
def main():
|
||||
context = json.load(sys.stdin)
|
||||
tool = context.get('tool')
|
||||
params = context.get('parameters', {})
|
||||
|
||||
# Only trigger on Write/Edit to Python files
|
||||
if tool not in ['Write', 'Edit']:
|
||||
sys.exit(0)
|
||||
|
||||
file_path = params.get('file_path', '')
|
||||
if not file_path.endswith('.py'):
|
||||
sys.exit(0)
|
||||
|
||||
# Run ruff
|
||||
print(f"🔍 Linting {file_path}...", file=sys.stderr)
|
||||
ruff_result = subprocess.run(
|
||||
['ruff', 'check', '--fix', file_path],
|
||||
capture_output=True,
|
||||
text=True
|
||||
)
|
||||
|
||||
if ruff_result.returncode != 0:
|
||||
print(f"⚠️ Ruff found issues:", file=sys.stderr)
|
||||
print(ruff_result.stdout, file=sys.stderr)
|
||||
|
||||
# Run black
|
||||
print(f"🎨 Formatting {file_path}...", file=sys.stderr)
|
||||
black_result = subprocess.run(
|
||||
['black', '--quiet', file_path],
|
||||
capture_output=True
|
||||
)
|
||||
|
||||
if black_result.returncode == 0:
|
||||
print(f"✅ Formatted successfully", file=sys.stderr)
|
||||
else:
|
||||
print(f"❌ Formatting failed", file=sys.stderr)
|
||||
|
||||
sys.exit(0)
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
```
|
||||
|
||||
### 5. Settings Configuration
|
||||
|
||||
**`.claude/settings.json`** (updated)
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": {
|
||||
"commands": [".claude/hooks/lint_python.py"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Documentation
|
||||
|
||||
**`.claude/AUTOMATION_README.md`**
|
||||
```markdown
|
||||
# Automation System for Python CLI Tool
|
||||
|
||||
## Generated On
|
||||
2025-01-23
|
||||
|
||||
## Session ID
|
||||
b2c3d4e5-f6a7-8901-bcde-f23456789012
|
||||
|
||||
## What Was Created
|
||||
|
||||
### Analysis Phase
|
||||
|
||||
- **code-quality-analyzer**: Identified 8 PEP 8 violations and 3 complex functions
|
||||
- **testing-analyzer**: Test coverage at 58%, many CLI commands untested
|
||||
|
||||
### Generated Artifacts
|
||||
|
||||
#### Custom Agents (4)
|
||||
- **code-quality-analyzer**: Evaluates code quality and PEP 8 compliance
|
||||
- **testing-analyzer**: Measures test coverage for CLI commands
|
||||
- **skill-generator**: Created 2 custom skills
|
||||
- **command-generator**: Created 2 slash commands
|
||||
|
||||
#### Skills (2)
|
||||
- **docstring-generator**: Auto-generates NumPy-style docstrings
|
||||
- **cli-test-helper**: Generates pytest tests for Click commands
|
||||
|
||||
#### Commands (2)
|
||||
- **/test-cov**: Run tests with coverage report
|
||||
- **/release-prep**: Prepare project for release
|
||||
|
||||
#### Hooks (1)
|
||||
- **PostToolUse**: Auto-lint and format Python files
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Generate docstrings:
|
||||
```bash
|
||||
"Add documentation to all functions in src/cli.py"
|
||||
# docstring-generator skill auto-invokes
|
||||
```
|
||||
|
||||
2. Generate tests:
|
||||
```bash
|
||||
"Create tests for the create_user command"
|
||||
# cli-test-helper skill auto-invokes
|
||||
```
|
||||
|
||||
3. Check coverage:
|
||||
```bash
|
||||
/test-cov
|
||||
```
|
||||
|
||||
4. Prepare release:
|
||||
```bash
|
||||
/release-prep patch
|
||||
```
|
||||
|
||||
5. Auto-formatting:
|
||||
- Every time you write/edit a .py file, it's automatically linted and formatted
|
||||
|
||||
## Customization
|
||||
|
||||
- Edit skills in `.claude/skills/`
|
||||
- Modify commands in `.claude/commands/`
|
||||
- Adjust hook in `.claude/hooks/lint_python.py`
|
||||
- Configure linters (ruff.toml, pyproject.toml)
|
||||
|
||||
[... more documentation ...]
|
||||
```
|
||||
|
||||
## Agent Communication
|
||||
|
||||
**`coordination.json`**
|
||||
```json
|
||||
{
|
||||
"session_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
|
||||
"started_at": "2025-01-23T14:00:00Z",
|
||||
"project_type": "cli",
|
||||
"agents": {
|
||||
"code-quality-analyzer": {
|
||||
"status": "completed",
|
||||
"started_at": "2025-01-23T14:00:00Z",
|
||||
"completed_at": "2025-01-23T14:03:00Z",
|
||||
"report_path": "reports/code-quality-analyzer.json"
|
||||
},
|
||||
"testing-analyzer": {
|
||||
"status": "completed",
|
||||
"started_at": "2025-01-23T14:00:01Z",
|
||||
"completed_at": "2025-01-23T14:04:00Z",
|
||||
"report_path": "reports/testing-analyzer.json"
|
||||
},
|
||||
"skill-generator": {
|
||||
"status": "completed",
|
||||
"started_at": "2025-01-23T14:05:00Z",
|
||||
"completed_at": "2025-01-23T14:08:00Z",
|
||||
"report_path": "reports/skill-generator.json"
|
||||
},
|
||||
"command-generator": {
|
||||
"status": "completed",
|
||||
"started_at": "2025-01-23T14:08:30Z",
|
||||
"completed_at": "2025-01-23T14:10:00Z",
|
||||
"report_path": "reports/command-generator.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Report Excerpts:**
|
||||
|
||||
**`reports/testing-analyzer.json`**
|
||||
```json
|
||||
{
|
||||
"agent_name": "testing-analyzer",
|
||||
"summary": "Test coverage at 58%. Many CLI commands lack tests.",
|
||||
"findings": [
|
||||
{
|
||||
"type": "issue",
|
||||
"severity": "high",
|
||||
"title": "Untested CLI Commands",
|
||||
"description": "5 Click commands have no tests",
|
||||
"location": "src/cli.py",
|
||||
"recommendation": "Generate tests for each command"
|
||||
}
|
||||
],
|
||||
"recommendations_for_automation": [
|
||||
"Skill: Auto-generate CLI tests using CliRunner",
|
||||
"Command: /test-cov for quick coverage checks"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**`reports/skill-generator.json`**
|
||||
```json
|
||||
{
|
||||
"agent_name": "skill-generator",
|
||||
"summary": "Generated 2 skills: docstring-generator and cli-test-helper",
|
||||
"findings": [
|
||||
{
|
||||
"type": "info",
|
||||
"title": "Created docstring-generator skill",
|
||||
"description": "Automates NumPy-style docstring generation",
|
||||
"location": ".claude/skills/docstring-generator/"
|
||||
},
|
||||
{
|
||||
"type": "info",
|
||||
"title": "Created cli-test-helper skill",
|
||||
"description": "Automates pytest test generation for Click commands",
|
||||
"location": ".claude/skills/cli-test-helper/"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Result
|
||||
|
||||
Solo developer now has efficient automation:
|
||||
- ✅ 2 skills that handle tedious documentation and testing tasks
|
||||
- ✅ 2 commands for common workflows (coverage, releases)
|
||||
- ✅ 1 hook that auto-formats on every save
|
||||
- ✅ Focuses on writing code, not boilerplate
|
||||
- ✅ Complete documentation
|
||||
- ✅ Ready to use immediately
|
||||
|
||||
Total generation time: ~10 minutes
|
||||
|
||||
## Before vs After
|
||||
|
||||
**Before:**
|
||||
```bash
|
||||
# Manual workflow
|
||||
$ vim src/cli.py # Add new command
|
||||
$ vim tests/test_cli.py # Manually write tests
|
||||
$ pytest # Run tests
|
||||
$ ruff check src/ # Manual linting
|
||||
$ black src/ # Manual formatting
|
||||
$ pytest --cov # Check coverage
|
||||
$ vim docs/ # Update docs manually
|
||||
# ~30-45 minutes per feature
|
||||
```
|
||||
|
||||
**After:**
|
||||
```bash
|
||||
# Automated workflow
|
||||
$ vim src/cli.py # Add new command
|
||||
# Hook auto-formats and lints immediately ✅
|
||||
|
||||
"Create tests for the new command"
|
||||
# cli-test-helper generates comprehensive tests ✅
|
||||
|
||||
/test-cov
|
||||
# Instant coverage report ✅
|
||||
|
||||
"Add docstrings to src/cli.py"
|
||||
# docstring-generator adds complete documentation ✅
|
||||
|
||||
# ~10 minutes per feature (3-4x faster!)
|
||||
```
|
||||
Reference in New Issue
Block a user