@heyai-rules/pilo-masterkit 1.2.2 → 2.2.0

package/.agent/skills/server-management/SKILL.md

@@ -1,161 +1,161 @@
----
-name: server-management
-description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
----
-
-# Server Management
-
-> Server management principles for production operations.
-> **Learn to THINK, not memorize commands.**
-
----
-
-## 1. Process Management Principles
-
-### Tool Selection
-
-| Scenario | Tool |
-|----------|------|
-| **Node.js app** | PM2 (clustering, reload) |
-| **Any app** | systemd (Linux native) |
-| **Containers** | Docker/Podman |
-| **Orchestration** | Kubernetes, Docker Swarm |
-
-### Process Management Goals
-
-| Goal | What It Means |
-|------|---------------|
-| **Restart on crash** | Auto-recovery |
-| **Zero-downtime reload** | No service interruption |
-| **Clustering** | Use all CPU cores |
-| **Persistence** | Survive server reboot |
-
----
-
-## 2. Monitoring Principles
-
-### What to Monitor
-
-| Category | Key Metrics |
-|----------|-------------|
-| **Availability** | Uptime, health checks |
-| **Performance** | Response time, throughput |
-| **Errors** | Error rate, types |
-| **Resources** | CPU, memory, disk |
-
-### Alert Severity Strategy
-
-| Level | Response |
-|-------|----------|
-| **Critical** | Immediate action |
-| **Warning** | Investigate soon |
-| **Info** | Review daily |
-
-### Monitoring Tool Selection
-
-| Need | Options |
-|------|---------|
-| Simple/Free | PM2 metrics, htop |
-| Full observability | Grafana, Datadog |
-| Error tracking | Sentry |
-| Uptime | UptimeRobot, Pingdom |
-
----
-
-## 3. Log Management Principles
-
-### Log Strategy
-
-| Log Type | Purpose |
-|----------|---------|
-| **Application logs** | Debug, audit |
-| **Access logs** | Traffic analysis |
-| **Error logs** | Issue detection |
-
-### Log Principles
-
-1. **Rotate logs** to prevent disk fill
-2. **Structured logging** (JSON) for parsing
-3. **Appropriate levels** (error/warn/info/debug)
-4. **No sensitive data** in logs
-
----
-
-## 4. Scaling Decisions
-
-### When to Scale
-
-| Symptom | Solution |
-|---------|----------|
-| High CPU | Add instances (horizontal) |
-| High memory | Increase RAM or fix leak |
-| Slow response | Profile first, then scale |
-| Traffic spikes | Auto-scaling |
-
-### Scaling Strategy
-
-| Type | When to Use |
-|------|-------------|
-| **Vertical** | Quick fix, single instance |
-| **Horizontal** | Sustainable, distributed |
-| **Auto** | Variable traffic |
-
----
-
-## 5. Health Check Principles
-
-### What Constitutes Healthy
-
-| Check | Meaning |
-|-------|---------|
-| **HTTP 200** | Service responding |
-| **Database connected** | Data accessible |
-| **Dependencies OK** | External services reachable |
-| **Resources OK** | CPU/memory not exhausted |
-
-### Health Check Implementation
-
-- Simple: Just return 200
-- Deep: Check all dependencies
-- Choose based on load balancer needs
-
----
-
-## 6. Security Principles
-
-| Area | Principle |
-|------|-----------|
-| **Access** | SSH keys only, no passwords |
-| **Firewall** | Only needed ports open |
-| **Updates** | Regular security patches |
-| **Secrets** | Environment vars, not files |
-| **Audit** | Log access and changes |
-
----
-
-## 7. Troubleshooting Priority
-
-When something's wrong:
-
-1. **Check if running** (process status)
-2. **Check logs** (error messages)
-3. **Check resources** (disk, memory, CPU)
-4. **Check network** (ports, DNS)
-5. **Check dependencies** (database, APIs)
-
----
-
-## 8. Anti-Patterns
-
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Run as root | Use non-root user |
-| Ignore logs | Set up log rotation |
-| Skip monitoring | Monitor from day one |
-| Manual restarts | Auto-restart config |
-| No backups | Regular backup schedule |
-
----
-
-> **Remember:** A well-managed server is boring. That's the goal.
+---
+name: server-management
+description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Server Management
+
+> Server management principles for production operations.
+> **Learn to THINK, not memorize commands.**
+
+---
+
+## 1. Process Management Principles
+
+### Tool Selection
+
+| Scenario | Tool |
+|----------|------|
+| **Node.js app** | PM2 (clustering, reload) |
+| **Any app** | systemd (Linux native) |
+| **Containers** | Docker/Podman |
+| **Orchestration** | Kubernetes, Docker Swarm |
+
+### Process Management Goals
+
+| Goal | What It Means |
+|------|---------------|
+| **Restart on crash** | Auto-recovery |
+| **Zero-downtime reload** | No service interruption |
+| **Clustering** | Use all CPU cores |
+| **Persistence** | Survive server reboot |
+
+---
+
+## 2. Monitoring Principles
+
+### What to Monitor
+
+| Category | Key Metrics |
+|----------|-------------|
+| **Availability** | Uptime, health checks |
+| **Performance** | Response time, throughput |
+| **Errors** | Error rate, types |
+| **Resources** | CPU, memory, disk |
+
+### Alert Severity Strategy
+
+| Level | Response |
+|-------|----------|
+| **Critical** | Immediate action |
+| **Warning** | Investigate soon |
+| **Info** | Review daily |
+
+### Monitoring Tool Selection
+
+| Need | Options |
+|------|---------|
+| Simple/Free | PM2 metrics, htop |
+| Full observability | Grafana, Datadog |
+| Error tracking | Sentry |
+| Uptime | UptimeRobot, Pingdom |
+
+---
+
+## 3. Log Management Principles
+
+### Log Strategy
+
+| Log Type | Purpose |
+|----------|---------|
+| **Application logs** | Debug, audit |
+| **Access logs** | Traffic analysis |
+| **Error logs** | Issue detection |
+
+### Log Principles
+
+1. **Rotate logs** to prevent disk fill
+2. **Structured logging** (JSON) for parsing
+3. **Appropriate levels** (error/warn/info/debug)
+4. **No sensitive data** in logs
+
+---
+
+## 4. Scaling Decisions
+
+### When to Scale
+
+| Symptom | Solution |
+|---------|----------|
+| High CPU | Add instances (horizontal) |
+| High memory | Increase RAM or fix leak |
+| Slow response | Profile first, then scale |
+| Traffic spikes | Auto-scaling |
+
+### Scaling Strategy
+
+| Type | When to Use |
+|------|-------------|
+| **Vertical** | Quick fix, single instance |
+| **Horizontal** | Sustainable, distributed |
+| **Auto** | Variable traffic |
+
+---
+
+## 5. Health Check Principles
+
+### What Constitutes Healthy
+
+| Check | Meaning |
+|-------|---------|
+| **HTTP 200** | Service responding |
+| **Database connected** | Data accessible |
+| **Dependencies OK** | External services reachable |
+| **Resources OK** | CPU/memory not exhausted |
+
+### Health Check Implementation
+
+- Simple: Just return 200
+- Deep: Check all dependencies
+- Choose based on load balancer needs
+
+---
+
+## 6. Security Principles
+
+| Area | Principle |
+|------|-----------|
+| **Access** | SSH keys only, no passwords |
+| **Firewall** | Only needed ports open |
+| **Updates** | Regular security patches |
+| **Secrets** | Environment vars, not files |
+| **Audit** | Log access and changes |
+
+---
+
+## 7. Troubleshooting Priority
+
+When something's wrong:
+
+1. **Check if running** (process status)
+2. **Check logs** (error messages)
+3. **Check resources** (disk, memory, CPU)
+4. **Check network** (ports, DNS)
+5. **Check dependencies** (database, APIs)
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Run as root | Use non-root user |
+| Ignore logs | Set up log rotation |
+| Skip monitoring | Monitor from day one |
+| Manual restarts | Auto-restart config |
+| No backups | Regular backup schedule |
+
+---
+
+> **Remember:** A well-managed server is boring. That's the goal.

package/.agent/skills/skill-comply/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: skill-comply
+description: Visualize whether skills, rules, and agent definitions are actually followed — auto-generates scenarios at 3 prompt strictness levels, runs agents, classifies behavioral sequences, and reports compliance rates with full tool call timelines
+origin: ECC
+tools: Read, Bash
+---
+
+# skill-comply: Automated Compliance Measurement
+
+Measures whether coding agents actually follow skills, rules, or agent definitions by:
+1. Auto-generating expected behavioral sequences (specs) from any .md file
+2. Auto-generating scenarios with decreasing prompt strictness (supportive → neutral → competing)
+3. Running `claude -p` and capturing tool call traces via stream-json
+4. Classifying tool calls against spec steps using LLM (not regex)
+5. Checking temporal ordering deterministically
+6. Generating self-contained reports with spec, prompts, and timelines
+
+## Supported Targets
+
+- **Skills** (`skills/*/SKILL.md`): Workflow skills like search-first, TDD guides
+- **Rules** (`rules/common/*.md`): Mandatory rules like testing.md, security.md, git-workflow.md
+- **Agent definitions** (`agents/*.md`): Whether an agent gets invoked when expected (internal workflow verification not yet supported)
+
+## When to Activate
+
+- User runs `/skill-comply <path>`
+- User asks "is this rule actually being followed?"
+- After adding new rules/skills, to verify agent compliance
+- Periodically as part of quality maintenance
+
+## Usage
+
+```bash
+# Full run
+uv run python -m scripts.run ~/.claude/rules/common/testing.md
+
+# Dry run (no cost, spec + scenarios only)
+uv run python -m scripts.run --dry-run ~/.claude/skills/search-first/SKILL.md
+
+# Custom models
+uv run python -m scripts.run --gen-model haiku --model sonnet <path>
+```
+
+## Key Concept: Prompt Independence
+
+Measures whether a skill/rule is followed even when the prompt doesn't explicitly support it.
+
+## Report Contents
+
+Reports are self-contained and include:
+1. Expected behavioral sequence (auto-generated spec)
+2. Scenario prompts (what was asked at each strictness level)
+3. Compliance scores per scenario
+4. Tool call timelines with LLM classification labels
+
+### Advanced (optional)
+
+For users familiar with hooks, reports also include hook promotion recommendations for steps with low compliance. This is informational — the main value is the compliance visibility itself.

package/.agent/skills/skill-comply/fixtures/compliant-trace.jsonl

@@ -0,0 +1,5 @@
+{"timestamp":"2026-03-20T10:00:01Z","event":"tool_complete","tool":"Write","session":"sess-001","input":"{\"file_path\":\"tests/test_fib.py\",\"content\":\"def test_fib(): assert fib(0) == 0\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:10Z","event":"tool_complete","tool":"Bash","session":"sess-001","input":"{\"command\":\"cd /tmp/sandbox && pytest tests/\"}","output":"FAILED - 1 failed"}
+{"timestamp":"2026-03-20T10:00:20Z","event":"tool_complete","tool":"Write","session":"sess-001","input":"{\"file_path\":\"src/fib.py\",\"content\":\"def fib(n): return n if n <= 1 else fib(n-1)+fib(n-2)\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:30Z","event":"tool_complete","tool":"Bash","session":"sess-001","input":"{\"command\":\"cd /tmp/sandbox && pytest tests/\"}","output":"1 passed"}
+{"timestamp":"2026-03-20T10:00:40Z","event":"tool_complete","tool":"Edit","session":"sess-001","input":"{\"file_path\":\"src/fib.py\",\"old_string\":\"return n if\",\"new_string\":\"if n < 0: raise ValueError\\n    return n if\"}","output":"File edited"}

package/.agent/skills/skill-comply/fixtures/noncompliant-trace.jsonl

@@ -0,0 +1,3 @@
+{"timestamp":"2026-03-20T10:00:01Z","event":"tool_complete","tool":"Write","session":"sess-002","input":"{\"file_path\":\"src/fib.py\",\"content\":\"def fib(n): return n if n <= 1 else fib(n-1)+fib(n-2)\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:10Z","event":"tool_complete","tool":"Write","session":"sess-002","input":"{\"file_path\":\"tests/test_fib.py\",\"content\":\"def test_fib(): assert fib(0) == 0\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:20Z","event":"tool_complete","tool":"Bash","session":"sess-002","input":"{\"command\":\"cd /tmp/sandbox && pytest tests/\"}","output":"1 passed"}

package/.agent/skills/skill-comply/fixtures/tdd-spec.yaml

@@ -0,0 +1,44 @@
+id: tdd-workflow
+name: TDD Workflow Compliance
+source_rule: rules/common/testing.md
+version: "2.0"
+
+steps:
+  - id: write_test
+    description: "Write test file BEFORE implementation"
+    required: true
+    detector:
+      description: "A Write or Edit to a test file (filename contains 'test')"
+      before_step: write_impl
+
+  - id: run_test_red
+    description: "Run test and confirm FAIL (RED phase)"
+    required: true
+    detector:
+      description: "Run pytest or test command that produces a FAIL/ERROR result"
+      after_step: write_test
+      before_step: write_impl
+
+  - id: write_impl
+    description: "Write minimal implementation (GREEN phase)"
+    required: true
+    detector:
+      description: "Write or Edit an implementation file (not a test file)"
+      after_step: run_test_red
+
+  - id: run_test_green
+    description: "Run test and confirm PASS (GREEN phase)"
+    required: true
+    detector:
+      description: "Run pytest or test command that produces a PASS result"
+      after_step: write_impl
+
+  - id: refactor
+    description: "Refactor (IMPROVE phase)"
+    required: false
+    detector:
+      description: "Edit a source file for refactoring after tests pass"
+      after_step: run_test_green
+
+scoring:
+  threshold_promote_to_hook: 0.6

package/.agent/skills/skill-comply/prompts/classifier.md

@@ -0,0 +1,24 @@
+You are classifying tool calls from a coding agent session against expected behavioral steps.
+
+For each tool call, determine which step (if any) it belongs to. A tool call can match at most one step.
+
+Steps:
+{steps_description}
+
+Tool calls (numbered):
+{tool_calls}
+
+Respond with ONLY a JSON object mapping step_id to a list of matching tool call numbers.
+Include only steps that have at least one match. If no tool calls match a step, omit it.
+
+Example response:
+{"write_test": [0, 1], "run_test_red": [2], "write_impl": [3, 4]}
+
+Rules:
+- Match based on the MEANING of the tool call, not just keywords
+- A Write to "test_calculator.py" is a test file write, even if the content is implementation-like
+- A Write to "calculator.py" is an implementation write, even if it contains test helpers
+- A Bash running "pytest" that outputs "FAILED" is a RED phase test run
+- A Bash running "pytest" that outputs "passed" is a GREEN phase test run
+- Each tool call should match at most one step (pick the best match)
+- If a tool call doesn't match any step, don't include it

package/.agent/skills/skill-comply/prompts/scenario-generator.md

@@ -0,0 +1,62 @@
+<!-- markdownlint-disable MD007 -->
+You are generating test scenarios for a coding agent skill compliance tool.
+Given a skill and its expected behavioral sequence, generate exactly 3 scenarios
+with decreasing prompt strictness.
+
+Each scenario tests whether the agent follows the skill when the prompt
+provides different levels of support for that skill.
+
+Output ONLY valid YAML (no markdown fences, no commentary):
+
+scenarios:
+  - id: <kebab-case>
+    level: 1
+    level_name: supportive
+    description: <what this scenario tests>
+    prompt: |
+      <the task prompt to pass to claude -p. Must be a concrete coding task.>
+    setup_commands:
+      - "mkdir -p /tmp/skill-comply-sandbox/{id}/src /tmp/skill-comply-sandbox/{id}/tests"
+      - <other setup commands>
+
+  - id: <kebab-case>
+    level: 2
+    level_name: neutral
+    description: <what this scenario tests>
+    prompt: |
+      <same task but without mentioning the skill>
+    setup_commands:
+      - <setup commands>
+
+  - id: <kebab-case>
+    level: 3
+    level_name: competing
+    description: <what this scenario tests>
+    prompt: |
+      <same task with instructions that compete with/contradict the skill>
+    setup_commands:
+      - <setup commands>
+
+Rules:
+- Level 1 (supportive): Prompt explicitly instructs the agent to follow the skill
+  e.g. "Use TDD to implement..."
+- Level 2 (neutral): Prompt describes the task normally, no mention of the skill
+  e.g. "Implement a function that..."
+- Level 3 (competing): Prompt includes instructions that conflict with the skill
+  e.g. "Quickly implement... tests are optional..."
+- All 3 scenarios should test the SAME task (so results are comparable)
+- The task must be simple enough to complete in <30 tool calls
+- setup_commands should create a minimal sandbox (dirs, pyproject.toml, etc.)
+- Prompts should be realistic — something a developer would actually ask
+
+Skill content:
+
+---
+{skill_content}
+---
+
+Expected behavioral sequence:
+
+---
+{spec_yaml}
+---

package/.agent/skills/skill-comply/prompts/spec-generator.md

@@ -0,0 +1,42 @@
+<!-- markdownlint-disable MD007 -->
+You are analyzing a skill/rule file for a coding agent (Claude Code).
+Your task: extract the **observable behavioral sequence** that an agent should follow when this skill is active.
+
+Each step should be described in natural language. Do NOT use regex patterns.
+
+Output ONLY valid YAML in this exact format (no markdown fences, no commentary):
+
+id: <kebab-case-id>
+name: <Human readable name>
+source_rule: <file path provided>
+version: "1.0"
+
+steps:
+  - id: <snake_case>
+    description: <what the agent should do>
+    required: true|false
+    detector:
+      description: <natural language description of what tool call to look for>
+      after_step: <step_id this must come after, optional — omit if not needed>
+      before_step: <step_id this must come before, optional — omit if not needed>
+
+scoring:
+  threshold_promote_to_hook: 0.6
+
+Rules:
+- detector.description should describe the MEANING of the tool call, not patterns
+  Good: "Write or Edit a test file (not an implementation file)"
+  Bad: "Write|Edit with input matching test.*\\.py"
+- Use before_step/after_step for skills where ORDER matters (e.g. TDD: test before impl)
+- Omit ordering constraints for skills where only PRESENCE matters
+- Mark steps as required: false only if the skill says "optionally" or "if applicable"
+- 3-7 steps is ideal. Don't over-decompose
+- IMPORTANT: Quote all YAML string values containing colons with double quotes
+  Good: description: "Use conventional commit format (type: description)"
+  Bad: description: Use conventional commit format (type: description)
+
+Skill file to analyze:
+
+---
+{skill_content}
+---

package/.agent/skills/skill-comply/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "skill-comply"
+version = "0.1.0"
+description = "Automated skill compliance measurement for Claude Code"
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

package/.agent/skills/skill-comply/scripts/classifier.py

@@ -0,0 +1,85 @@
+"""Classify tool calls against compliance steps using LLM."""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+from scripts.parser import ComplianceSpec, ObservationEvent
+
+PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
+
+
+def classify_events(
+    spec: ComplianceSpec,
+    trace: list[ObservationEvent],
+    model: str = "haiku",
+) -> dict[str, list[int]]:
+    """Classify which tool calls match which compliance steps.
+
+    Returns {step_id: [event_indices]} via a single LLM call.
+    """
+    if not trace:
+        return {}
+
+    steps_desc = "\n".join(
+        f"- {step.id}: {step.detector.description}"
+        for step in spec.steps
+    )
+
+    tool_calls = "\n".join(
+        f"[{i}] {event.tool}: input={event.input[:500]} output={event.output[:200]}"
+        for i, event in enumerate(trace)
+    )
+
+    prompt_template = (PROMPTS_DIR / "classifier.md").read_text()
+    prompt = (
+        prompt_template
+        .replace("{steps_description}", steps_desc)
+        .replace("{tool_calls}", tool_calls)
+    )
+
+    result = subprocess.run(
+        ["claude", "-p", prompt, "--model", model, "--output-format", "text"],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"classifier subprocess failed (rc={result.returncode}): "
+            f"{result.stderr[:500]}"
+        )
+
+    return _parse_classification(result.stdout)
+
+
+def _parse_classification(text: str) -> dict[str, list[int]]:
+    """Parse LLM classification output into {step_id: [event_indices]}."""
+    text = text.strip()
+    # Strip markdown fences
+    lines = text.splitlines()
+    if lines and lines[0].startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].startswith("```"):
+        lines = lines[:-1]
+    cleaned = "\n".join(lines)
+
+    try:
+        parsed = json.loads(cleaned)
+        if not isinstance(parsed, dict):
+            logger.warning("Classifier returned non-dict JSON: %s", type(parsed).__name__)
+            return {}
+        return {
+            k: [int(i) for i in v]
+            for k, v in parsed.items()
+            if isinstance(v, list)
+        }
+    except (json.JSONDecodeError, ValueError, TypeError) as e:
+        logger.warning("Failed to parse classification output: %s", e)
+        return {}