@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/django-verification/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: django-verification
+description: "Verification loop for Django projects: migrations, linting, tests with coverage, security scans, and deployment readiness checks before release or PR."
+origin: ECC
+---
+
+# Django Verification Loop
+
+Run before PRs, after major changes, and pre-deploy to ensure Django application quality and security.
+
+## When to Activate
+
+- Before opening a pull request for a Django project
+- After major model changes, migration updates, or dependency upgrades
+- Pre-deployment verification for staging or production
+- Running full environment → lint → test → security → deploy readiness pipeline
+- Validating migration safety and test coverage
+
+## Phase 1: Environment Check
+
+```bash
+# Verify Python version
+python --version  # Should match project requirements
+
+# Check virtual environment
+which python
+pip list --outdated
+
+# Verify environment variables
+python -c "import os; import environ; print('DJANGO_SECRET_KEY set' if os.environ.get('DJANGO_SECRET_KEY') else 'MISSING: DJANGO_SECRET_KEY')"
+```
+
+If environment is misconfigured, stop and fix.
+
+## Phase 2: Code Quality & Formatting
+
+```bash
+# Type checking
+mypy . --config-file pyproject.toml
+
+# Linting with ruff
+ruff check . --fix
+
+# Formatting with black
+black . --check
+black .  # Auto-fix
+
+# Import sorting
+isort . --check-only
+isort .  # Auto-fix
+
+# Django-specific checks
+python manage.py check --deploy
+```
+
+Common issues:
+- Missing type hints on public functions
+- PEP 8 formatting violations
+- Unsorted imports
+- Debug settings left in production configuration
+
+## Phase 3: Migrations
+
+```bash
+# Check for unapplied migrations
+python manage.py showmigrations
+
+# Create missing migrations
+python manage.py makemigrations --check
+
+# Dry-run migration application
+python manage.py migrate --plan
+
+# Apply migrations (test environment)
+python manage.py migrate
+
+# Check for migration conflicts
+python manage.py makemigrations --merge  # Only if conflicts exist
+```
+
+Report:
+- Number of pending migrations
+- Any migration conflicts
+- Model changes without migrations
+
+## Phase 4: Tests + Coverage
+
+```bash
+# Run all tests with pytest
+pytest --cov=apps --cov-report=html --cov-report=term-missing --reuse-db
+
+# Run specific app tests
+pytest apps/users/tests/
+
+# Run with markers
+pytest -m "not slow"  # Skip slow tests
+pytest -m integration  # Only integration tests
+
+# Coverage report
+open htmlcov/index.html
+```
+
+Report:
+- Total tests: X passed, Y failed, Z skipped
+- Overall coverage: XX%
+- Per-app coverage breakdown
+
+Coverage targets:
+
+| Component | Target |
+|-----------|--------|
+| Models | 90%+ |
+| Serializers | 85%+ |
+| Views | 80%+ |
+| Services | 90%+ |
+| Overall | 80%+ |
+
+## Phase 5: Security Scan
+
+```bash
+# Dependency vulnerabilities
+pip-audit
+safety check --full-report
+
+# Django security checks
+python manage.py check --deploy
+
+# Bandit security linter
+bandit -r . -f json -o bandit-report.json
+
+# Secret scanning (if gitleaks is installed)
+gitleaks detect --source . --verbose
+
+# Environment variable check
+python -c "from django.core.exceptions import ImproperlyConfigured; from django.conf import settings; settings.DEBUG"
+```
+
+Report:
+- Vulnerable dependencies found
+- Security configuration issues
+- Hardcoded secrets detected
+- DEBUG mode status (should be False in production)
+
+## Phase 6: Django Management Commands
+
+```bash
+# Check for model issues
+python manage.py check
+
+# Collect static files
+python manage.py collectstatic --noinput --clear
+
+# Create superuser (if needed for tests)
+echo "from apps.users.models import User; User.objects.create_superuser('admin@example.com', 'admin')" | python manage.py shell
+
+# Database integrity
+python manage.py check --database default
+
+# Cache verification (if using Redis)
+python -c "from django.core.cache import cache; cache.set('test', 'value', 10); print(cache.get('test'))"
+```
+
+## Phase 7: Performance Checks
+
+```bash
+# Django Debug Toolbar output (check for N+1 queries)
+# Run in dev mode with DEBUG=True and access a page
+# Look for duplicate queries in SQL panel
+
+# Query count analysis
+django-admin debugsqlshell  # If django-debug-sqlshell installed
+
+# Check for missing indexes
+python manage.py shell << EOF
+from django.db import connection
+with connection.cursor() as cursor:
+    cursor.execute("SELECT table_name, index_name FROM information_schema.statistics WHERE table_schema = 'public'")
+    print(cursor.fetchall())
+EOF
+```
+
+Report:
+- Number of queries per page (should be < 50 for typical pages)
+- Missing database indexes
+- Duplicate queries detected
+
+## Phase 8: Static Assets
+
+```bash
+# Check for npm dependencies (if using npm)
+npm audit
+npm audit fix
+
+# Build static files (if using webpack/vite)
+npm run build
+
+# Verify static files
+ls -la staticfiles/
+python manage.py findstatic css/style.css
+```
+
+## Phase 9: Configuration Review
+
+```python
+# Run in Python shell to verify settings
+python manage.py shell << EOF
+from django.conf import settings
+import os
+
+# Critical checks
+checks = {
+    'DEBUG is False': not settings.DEBUG,
+    'SECRET_KEY set': bool(settings.SECRET_KEY and len(settings.SECRET_KEY) > 30),
+    'ALLOWED_HOSTS set': len(settings.ALLOWED_HOSTS) > 0,
+    'HTTPS enabled': getattr(settings, 'SECURE_SSL_REDIRECT', False),
+    'HSTS enabled': getattr(settings, 'SECURE_HSTS_SECONDS', 0) > 0,
+    'Database configured': settings.DATABASES['default']['ENGINE'] != 'django.db.backends.sqlite3',
+}
+
+for check, result in checks.items():
+    status = '✓' if result else '✗'
+    print(f"{status} {check}")
+EOF
+```
+
+## Phase 10: Logging Configuration
+
+```bash
+# Test logging output
+python manage.py shell << EOF
+import logging
+logger = logging.getLogger('django')
+logger.warning('Test warning message')
+logger.error('Test error message')
+EOF
+
+# Check log files (if configured)
+tail -f /var/log/django/django.log
+```
+
+## Phase 11: API Documentation (if DRF)
+
+```bash
+# Generate schema
+python manage.py generateschema --format openapi-json > schema.json
+
+# Validate schema
+# Check if schema.json is valid JSON
+python -c "import json; json.load(open('schema.json'))"
+
+# Access Swagger UI (if using drf-yasg)
+# Visit http://localhost:8000/swagger/ in browser
+```
+
+## Phase 12: Diff Review
+
+```bash
+# Show diff statistics
+git diff --stat
+
+# Show actual changes
+git diff
+
+# Show changed files
+git diff --name-only
+
+# Check for common issues
+git diff | grep -i "todo\|fixme\|hack\|xxx"
+git diff | grep "print("  # Debug statements
+git diff | grep "DEBUG = True"  # Debug mode
+git diff | grep "import pdb"  # Debugger
+```
+
+Checklist:
+- No debugging statements (print, pdb, breakpoint())
+- No TODO/FIXME comments in critical code
+- No hardcoded secrets or credentials
+- Database migrations included for model changes
+- Configuration changes documented
+- Error handling present for external calls
+- Transaction management where needed
+
+## Output Template
+
+```
+DJANGO VERIFICATION REPORT
+==========================
+
+Phase 1: Environment Check
+  ✓ Python 3.11.5
+  ✓ Virtual environment active
+  ✓ All environment variables set
+
+Phase 2: Code Quality
+  ✓ mypy: No type errors
+  ✗ ruff: 3 issues found (auto-fixed)
+  ✓ black: No formatting issues
+  ✓ isort: Imports properly sorted
+  ✓ manage.py check: No issues
+
+Phase 3: Migrations
+  ✓ No unapplied migrations
+  ✓ No migration conflicts
+  ✓ All models have migrations
+
+Phase 4: Tests + Coverage
+  Tests: 247 passed, 0 failed, 5 skipped
+  Coverage:
+    Overall: 87%
+    users: 92%
+    products: 89%
+    orders: 85%
+    payments: 91%
+
+Phase 5: Security Scan
+  ✗ pip-audit: 2 vulnerabilities found (fix required)
+  ✓ safety check: No issues
+  ✓ bandit: No security issues
+  ✓ No secrets detected
+  ✓ DEBUG = False
+
+Phase 6: Django Commands
+  ✓ collectstatic completed
+  ✓ Database integrity OK
+  ✓ Cache backend reachable
+
+Phase 7: Performance
+  ✓ No N+1 queries detected
+  ✓ Database indexes configured
+  ✓ Query count acceptable
+
+Phase 8: Static Assets
+  ✓ npm audit: No vulnerabilities
+  ✓ Assets built successfully
+  ✓ Static files collected
+
+Phase 9: Configuration
+  ✓ DEBUG = False
+  ✓ SECRET_KEY configured
+  ✓ ALLOWED_HOSTS set
+  ✓ HTTPS enabled
+  ✓ HSTS enabled
+  ✓ Database configured
+
+Phase 10: Logging
+  ✓ Logging configured
+  ✓ Log files writable
+
+Phase 11: API Documentation
+  ✓ Schema generated
+  ✓ Swagger UI accessible
+
+Phase 12: Diff Review
+  Files changed: 12
+  +450, -120 lines
+  ✓ No debug statements
+  ✓ No hardcoded secrets
+  ✓ Migrations included
+
+RECOMMENDATION: WARNING: Fix pip-audit vulnerabilities before deploying
+
+NEXT STEPS:
+1. Update vulnerable dependencies
+2. Re-run security scan
+3. Deploy to staging for final testing
+```
+
+## Pre-Deployment Checklist
+
+- [ ] All tests passing
+- [ ] Coverage ≥ 80%
+- [ ] No security vulnerabilities
+- [ ] No unapplied migrations
+- [ ] DEBUG = False in production settings
+- [ ] SECRET_KEY properly configured
+- [ ] ALLOWED_HOSTS set correctly
+- [ ] Database backups enabled
+- [ ] Static files collected and served
+- [ ] Logging configured and working
+- [ ] Error monitoring (Sentry, etc.) configured
+- [ ] CDN configured (if applicable)
+- [ ] Redis/cache backend configured
+- [ ] Celery workers running (if applicable)
+- [ ] HTTPS/SSL configured
+- [ ] Environment variables documented
+
+## Continuous Integration
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/django-verification.yml
+name: Django Verification
+
+on: [push, pull_request]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:14
+        env:
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install ruff black mypy pytest pytest-django pytest-cov bandit safety pip-audit
+
+      - name: Code quality checks
+        run: |
+          ruff check .
+          black . --check
+          isort . --check-only
+          mypy .
+
+      - name: Security scan
+        run: |
+          bandit -r . -f json -o bandit-report.json
+          safety check --full-report
+          pip-audit
+
+      - name: Run tests
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test
+          DJANGO_SECRET_KEY: test-secret-key
+        run: |
+          pytest --cov=apps --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+```
+
+## Quick Reference
+
+| Check | Command |
+|-------|---------|
+| Environment | `python --version` |
+| Type checking | `mypy .` |
+| Linting | `ruff check .` |
+| Formatting | `black . --check` |
+| Migrations | `python manage.py makemigrations --check` |
+| Tests | `pytest --cov=apps` |
+| Security | `pip-audit && bandit -r .` |
+| Django check | `python manage.py check --deploy` |
+| Collectstatic | `python manage.py collectstatic --noinput` |
+| Diff stats | `git diff --stat` |
+
+Remember: Automated verification catches common issues but doesn't replace manual code review and testing in staging environment.

package/.agent/skills/dmux-workflows/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: dmux-workflows
+description: Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.
+origin: ECC
+---
+
+# dmux Workflows
+
+Orchestrate parallel AI agent sessions using dmux, a tmux pane manager for agent harnesses.
+
+## When to Activate
+
+- Running multiple agent sessions in parallel
+- Coordinating work across Claude Code, Codex, and other harnesses
+- Complex tasks that benefit from divide-and-conquer parallelism
+- User says "run in parallel", "split this work", "use dmux", or "multi-agent"
+
+## What is dmux
+
+dmux is a tmux-based orchestration tool that manages AI agent panes:
+- Press `n` to create a new pane with a prompt
+- Press `m` to merge pane output back to the main session
+- Supports: Claude Code, Codex, OpenCode, Cline, Gemini, Qwen
+
+**Install:** Install dmux from its repository after reviewing the package. See [github.com/standardagents/dmux](https://github.com/standardagents/dmux)
+
+## Quick Start
+
+```bash
+# Start dmux session
+dmux
+
+# Create agent panes (press 'n' in dmux, then type prompt)
+# Pane 1: "Implement the auth middleware in src/auth/"
+# Pane 2: "Write tests for the user service"
+# Pane 3: "Update API documentation"
+
+# Each pane runs its own agent session
+# Press 'm' to merge results back
+```
+
+## Workflow Patterns
+
+### Pattern 1: Research + Implement
+
+Split research and implementation into parallel tracks:
+
+```
+Pane 1 (Research): "Research best practices for rate limiting in Node.js.
+  Check current libraries, compare approaches, and write findings to
+  /tmp/rate-limit-research.md"
+
+Pane 2 (Implement): "Implement rate limiting middleware for our Express API.
+  Start with a basic token bucket, we'll refine after research completes."
+
+# After Pane 1 completes, merge findings into Pane 2's context
+```
+
+### Pattern 2: Multi-File Feature
+
+Parallelize work across independent files:
+
+```
+Pane 1: "Create the database schema and migrations for the billing feature"
+Pane 2: "Build the billing API endpoints in src/api/billing/"
+Pane 3: "Create the billing dashboard UI components"
+
+# Merge all, then do integration in main pane
+```
+
+### Pattern 3: Test + Fix Loop
+
+Run tests in one pane, fix in another:
+
+```
+Pane 1 (Watcher): "Run the test suite in watch mode. When tests fail,
+  summarize the failures."
+
+Pane 2 (Fixer): "Fix failing tests based on the error output from pane 1"
+```
+
+### Pattern 4: Cross-Harness
+
+Use different AI tools for different tasks:
+
+```
+Pane 1 (Claude Code): "Review the security of the auth module"
+Pane 2 (Codex): "Refactor the utility functions for performance"
+Pane 3 (Claude Code): "Write E2E tests for the checkout flow"
+```
+
+### Pattern 5: Code Review Pipeline
+
+Parallel review perspectives:
+
+```
+Pane 1: "Review src/api/ for security vulnerabilities"
+Pane 2: "Review src/api/ for performance issues"
+Pane 3: "Review src/api/ for test coverage gaps"
+
+# Merge all reviews into a single report
+```
+
+## Best Practices
+
+1. **Independent tasks only.** Don't parallelize tasks that depend on each other's output.
+2. **Clear boundaries.** Each pane should work on distinct files or concerns.
+3. **Merge strategically.** Review pane output before merging to avoid conflicts.
+4. **Use git worktrees.** For file-conflict-prone work, use separate worktrees per pane.
+5. **Resource awareness.** Each pane uses API tokens — keep total panes under 5-6.
+
+## Git Worktree Integration
+
+For tasks that touch overlapping files:
+
+```bash
+# Create worktrees for isolation
+git worktree add -b feat/auth ../feature-auth HEAD
+git worktree add -b feat/billing ../feature-billing HEAD
+
+# Run agents in separate worktrees
+# Pane 1: cd ../feature-auth && claude
+# Pane 2: cd ../feature-billing && claude
+
+# Merge branches when done
+git merge feat/auth
+git merge feat/billing
+```
+
+## Complementary Tools
+
+| Tool | What It Does | When to Use |
+|------|-------------|-------------|
+| **dmux** | tmux pane management for agents | Parallel agent sessions |
+| **Superset** | Terminal IDE for 10+ parallel agents | Large-scale orchestration |
+| **Claude Code Task tool** | In-process subagent spawning | Programmatic parallelism within a session |
+| **Codex multi-agent** | Built-in agent roles | Codex-specific parallel work |
+
+## ECC Helper
+
+ECC now includes a helper for external tmux-pane orchestration with separate git worktrees:
+
+```bash
+node scripts/orchestrate-worktrees.js plan.json --execute
+```
+
+Example `plan.json`:
+
+```json
+{
+  "sessionName": "skill-audit",
+  "baseRef": "HEAD",
+  "launcherCommand": "codex exec --cwd {worktree_path} --task-file {task_file}",
+  "workers": [
+    { "name": "docs-a", "task": "Fix skills 1-4 and write handoff notes." },
+    { "name": "docs-b", "task": "Fix skills 5-8 and write handoff notes." }
+  ]
+}
+```
+
+The helper:
+- Creates one branch-backed git worktree per worker
+- Optionally overlays selected `seedPaths` from the main checkout into each worker worktree
+- Writes per-worker `task.md`, `handoff.md`, and `status.md` files under `.orchestration/<session>/`
+- Starts a tmux session with one pane per worker
+- Launches each worker command in its own pane
+- Leaves the main pane free for the orchestrator
+
+Use `seedPaths` when workers need access to dirty or untracked local files that are not yet part of `HEAD`, such as local orchestration scripts, draft plans, or docs:
+
+```json
+{
+  "sessionName": "workflow-e2e",
+  "seedPaths": [
+    "scripts/orchestrate-worktrees.js",
+    "scripts/lib/tmux-worktree-orchestrator.js",
+    ".claude/plan/workflow-e2e-test.json"
+  ],
+  "launcherCommand": "bash {repo_root}/scripts/orchestrate-codex-worker.sh {task_file} {handoff_file} {status_file}",
+  "workers": [
+    { "name": "seed-check", "task": "Verify seeded files are present before starting work." }
+  ]
+}
+```
+
+## Troubleshooting
+
+- **Pane not responding:** Switch to the pane directly or inspect it with `tmux capture-pane -pt <session>:0.<pane-index>`.
+- **Merge conflicts:** Use git worktrees to isolate file changes per pane.
+- **High token usage:** Reduce number of parallel panes. Each pane is a full agent session.
+- **tmux not found:** Install with `brew install tmux` (macOS) or `apt install tmux` (Linux).