@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/skills/ralphinho-rfc-pipeline/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ralphinho-rfc-pipeline
+description: RFC-driven multi-agent DAG execution pattern with quality gates, merge queues, and work unit orchestration.
+origin: ECC
+---
+
+# Ralphinho RFC Pipeline
+
+Inspired by [humanplane](https://github.com/humanplane) style RFC decomposition patterns and multi-unit orchestration workflows.
+
+Use this skill when a feature is too large for a single agent pass and must be split into independently verifiable work units.
+
+## Pipeline Stages
+
+1. RFC intake
+2. DAG decomposition
+3. Unit assignment
+4. Unit implementation
+5. Unit validation
+6. Merge queue and integration
+7. Final system verification
+
+## Unit Spec Template
+
+Each work unit should include:
+- `id`
+- `depends_on`
+- `scope`
+- `acceptance_tests`
+- `risk_level`
+- `rollback_plan`
+
+## Complexity Tiers
+
+- Tier 1: isolated file edits, deterministic tests
+- Tier 2: multi-file behavior changes, moderate integration risk
+- Tier 3: schema/auth/perf/security changes
+
+## Quality Pipeline per Unit
+
+1. research
+2. implementation plan
+3. implementation
+4. tests
+5. review
+6. merge-ready report
+
+## Merge Queue Rules
+
+- Never merge a unit with unresolved dependency failures.
+- Always rebase unit branches on latest integration branch.
+- Re-run integration tests after each queued merge.
+
+## Recovery
+
+If a unit stalls:
+- evict from active queue
+- snapshot findings
+- regenerate narrowed unit scope
+- retry with updated constraints
+
+## Outputs
+
+- RFC execution log
+- unit scorecards
+- dependency graph snapshot
+- integration risk summary

package/.agent/skills/red-team-tactics/SKILL.md

@@ -1,199 +1,199 @@
----
-name: red-team-tactics
-description: Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting.
-allowed-tools: Read, Glob, Grep
----
-
-# Red Team Tactics
-
-> Adversary simulation principles based on MITRE ATT&CK framework.
-
----
-
-## 1. MITRE ATT&CK Phases
-
-### Attack Lifecycle
-
-```
-RECONNAISSANCE → INITIAL ACCESS → EXECUTION → PERSISTENCE
-       ↓              ↓              ↓            ↓
-   PRIVILEGE ESC → DEFENSE EVASION → CRED ACCESS → DISCOVERY
-       ↓              ↓              ↓            ↓
-LATERAL MOVEMENT → COLLECTION → C2 → EXFILTRATION → IMPACT
-```
-
-### Phase Objectives
-
-| Phase | Objective |
-|-------|-----------|
-| **Recon** | Map attack surface |
-| **Initial Access** | Get first foothold |
-| **Execution** | Run code on target |
-| **Persistence** | Survive reboots |
-| **Privilege Escalation** | Get admin/root |
-| **Defense Evasion** | Avoid detection |
-| **Credential Access** | Harvest credentials |
-| **Discovery** | Map internal network |
-| **Lateral Movement** | Spread to other systems |
-| **Collection** | Gather target data |
-| **C2** | Maintain command channel |
-| **Exfiltration** | Extract data |
-
----
-
-## 2. Reconnaissance Principles
-
-### Passive vs Active
-
-| Type | Trade-off |
-|------|-----------|
-| **Passive** | No target contact, limited info |
-| **Active** | Direct contact, more detection risk |
-
-### Information Targets
-
-| Category | Value |
-|----------|-------|
-| Technology stack | Attack vector selection |
-| Employee info | Social engineering |
-| Network ranges | Scanning scope |
-| Third parties | Supply chain attack |
-
----
-
-## 3. Initial Access Vectors
-
-### Selection Criteria
-
-| Vector | When to Use |
-|--------|-------------|
-| **Phishing** | Human target, email access |
-| **Public exploits** | Vulnerable services exposed |
-| **Valid credentials** | Leaked or cracked |
-| **Supply chain** | Third-party access |
-
----
-
-## 4. Privilege Escalation Principles
-
-### Windows Targets
-
-| Check | Opportunity |
-|-------|-------------|
-| Unquoted service paths | Write to path |
-| Weak service permissions | Modify service |
-| Token privileges | Abuse SeDebug, etc. |
-| Stored credentials | Harvest |
-
-### Linux Targets
-
-| Check | Opportunity |
-|-------|-------------|
-| SUID binaries | Execute as owner |
-| Sudo misconfiguration | Command execution |
-| Kernel vulnerabilities | Kernel exploits |
-| Cron jobs | Writable scripts |
-
----
-
-## 5. Defense Evasion Principles
-
-### Key Techniques
-
-| Technique | Purpose |
-|-----------|---------|
-| LOLBins | Use legitimate tools |
-| Obfuscation | Hide malicious code |
-| Timestomping | Hide file modifications |
-| Log clearing | Remove evidence |
-
-### Operational Security
-
-- Work during business hours
-- Mimic legitimate traffic patterns
-- Use encrypted channels
-- Blend with normal behavior
-
----
-
-## 6. Lateral Movement Principles
-
-### Credential Types
-
-| Type | Use |
-|------|-----|
-| Password | Standard auth |
-| Hash | Pass-the-hash |
-| Ticket | Pass-the-ticket |
-| Certificate | Certificate auth |
-
-### Movement Paths
-
-- Admin shares
-- Remote services (RDP, SSH, WinRM)
-- Exploitation of internal services
-
----
-
-## 7. Active Directory Attacks
-
-### Attack Categories
-
-| Attack | Target |
-|--------|--------|
-| Kerberoasting | Service account passwords |
-| AS-REP Roasting | Accounts without pre-auth |
-| DCSync | Domain credentials |
-| Golden Ticket | Persistent domain access |
-
----
-
-## 8. Reporting Principles
-
-### Attack Narrative
-
-Document the full attack chain:
-1. How initial access was gained
-2. What techniques were used
-3. What objectives were achieved
-4. Where detection failed
-
-### Detection Gaps
-
-For each successful technique:
-- What should have detected it?
-- Why didn't detection work?
-- How to improve detection
-
----
-
-## 9. Ethical Boundaries
-
-### Always
-
-- Stay within scope
-- Minimize impact
-- Report immediately if real threat found
-- Document all actions
-
-### Never
-
-- Destroy production data
-- Cause denial of service (unless scoped)
-- Access beyond proof of concept
-- Retain sensitive data
-
----
-
-## 10. Anti-Patterns
-
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Rush to exploitation | Follow methodology |
-| Cause damage | Minimize impact |
-| Skip reporting | Document everything |
-| Ignore scope | Stay within boundaries |
-
----
-
-> **Remember:** Red team simulates attackers to improve defenses, not to cause harm.
+---
+name: red-team-tactics
+description: Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting.
+allowed-tools: Read, Glob, Grep
+---
+
+# Red Team Tactics
+
+> Adversary simulation principles based on MITRE ATT&CK framework.
+
+---
+
+## 1. MITRE ATT&CK Phases
+
+### Attack Lifecycle
+
+```
+RECONNAISSANCE → INITIAL ACCESS → EXECUTION → PERSISTENCE
+       ↓              ↓              ↓            ↓
+   PRIVILEGE ESC → DEFENSE EVASION → CRED ACCESS → DISCOVERY
+       ↓              ↓              ↓            ↓
+LATERAL MOVEMENT → COLLECTION → C2 → EXFILTRATION → IMPACT
+```
+
+### Phase Objectives
+
+| Phase | Objective |
+|-------|-----------|
+| **Recon** | Map attack surface |
+| **Initial Access** | Get first foothold |
+| **Execution** | Run code on target |
+| **Persistence** | Survive reboots |
+| **Privilege Escalation** | Get admin/root |
+| **Defense Evasion** | Avoid detection |
+| **Credential Access** | Harvest credentials |
+| **Discovery** | Map internal network |
+| **Lateral Movement** | Spread to other systems |
+| **Collection** | Gather target data |
+| **C2** | Maintain command channel |
+| **Exfiltration** | Extract data |
+
+---
+
+## 2. Reconnaissance Principles
+
+### Passive vs Active
+
+| Type | Trade-off |
+|------|-----------|
+| **Passive** | No target contact, limited info |
+| **Active** | Direct contact, more detection risk |
+
+### Information Targets
+
+| Category | Value |
+|----------|-------|
+| Technology stack | Attack vector selection |
+| Employee info | Social engineering |
+| Network ranges | Scanning scope |
+| Third parties | Supply chain attack |
+
+---
+
+## 3. Initial Access Vectors
+
+### Selection Criteria
+
+| Vector | When to Use |
+|--------|-------------|
+| **Phishing** | Human target, email access |
+| **Public exploits** | Vulnerable services exposed |
+| **Valid credentials** | Leaked or cracked |
+| **Supply chain** | Third-party access |
+
+---
+
+## 4. Privilege Escalation Principles
+
+### Windows Targets
+
+| Check | Opportunity |
+|-------|-------------|
+| Unquoted service paths | Write to path |
+| Weak service permissions | Modify service |
+| Token privileges | Abuse SeDebug, etc. |
+| Stored credentials | Harvest |
+
+### Linux Targets
+
+| Check | Opportunity |
+|-------|-------------|
+| SUID binaries | Execute as owner |
+| Sudo misconfiguration | Command execution |
+| Kernel vulnerabilities | Kernel exploits |
+| Cron jobs | Writable scripts |
+
+---
+
+## 5. Defense Evasion Principles
+
+### Key Techniques
+
+| Technique | Purpose |
+|-----------|---------|
+| LOLBins | Use legitimate tools |
+| Obfuscation | Hide malicious code |
+| Timestomping | Hide file modifications |
+| Log clearing | Remove evidence |
+
+### Operational Security
+
+- Work during business hours
+- Mimic legitimate traffic patterns
+- Use encrypted channels
+- Blend with normal behavior
+
+---
+
+## 6. Lateral Movement Principles
+
+### Credential Types
+
+| Type | Use |
+|------|-----|
+| Password | Standard auth |
+| Hash | Pass-the-hash |
+| Ticket | Pass-the-ticket |
+| Certificate | Certificate auth |
+
+### Movement Paths
+
+- Admin shares
+- Remote services (RDP, SSH, WinRM)
+- Exploitation of internal services
+
+---
+
+## 7. Active Directory Attacks
+
+### Attack Categories
+
+| Attack | Target |
+|--------|--------|
+| Kerberoasting | Service account passwords |
+| AS-REP Roasting | Accounts without pre-auth |
+| DCSync | Domain credentials |
+| Golden Ticket | Persistent domain access |
+
+---
+
+## 8. Reporting Principles
+
+### Attack Narrative
+
+Document the full attack chain:
+1. How initial access was gained
+2. What techniques were used
+3. What objectives were achieved
+4. Where detection failed
+
+### Detection Gaps
+
+For each successful technique:
+- What should have detected it?
+- Why didn't detection work?
+- How to improve detection
+
+---
+
+## 9. Ethical Boundaries
+
+### Always
+
+- Stay within scope
+- Minimize impact
+- Report immediately if real threat found
+- Document all actions
+
+### Never
+
+- Destroy production data
+- Cause denial of service (unless scoped)
+- Access beyond proof of concept
+- Retain sensitive data
+
+---
+
+## 10. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Rush to exploitation | Follow methodology |
+| Cause damage | Minimize impact |
+| Skip reporting | Document everything |
+| Ignore scope | Stay within boundaries |
+
+---
+
+> **Remember:** Red team simulates attackers to improve defenses, not to cause harm.

package/.agent/skills/regex-vs-llm-structured-text/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: regex-vs-llm-structured-text
+description: Decision framework for choosing between regex and LLM when parsing structured text — start with regex, add LLM only for low-confidence edge cases.
+origin: ECC
+---
+
+# Regex vs LLM for Structured Text Parsing
+
+A practical decision framework for parsing structured text (quizzes, forms, invoices, documents). The key insight: regex handles 95-98% of cases cheaply and deterministically. Reserve expensive LLM calls for the remaining edge cases.
+
+## When to Activate
+
+- Parsing structured text with repeating patterns (questions, forms, tables)
+- Deciding between regex and LLM for text extraction
+- Building hybrid pipelines that combine both approaches
+- Optimizing cost/accuracy tradeoffs in text processing
+
+## Decision Framework
+
+```
+Is the text format consistent and repeating?
+├── Yes (>90% follows a pattern) → Start with Regex
+│   ├── Regex handles 95%+ → Done, no LLM needed
+│   └── Regex handles <95% → Add LLM for edge cases only
+└── No (free-form, highly variable) → Use LLM directly
+```
+
+## Architecture Pattern
+
+```
+Source Text
+    │
+    ▼
+[Regex Parser] ─── Extracts structure (95-98% accuracy)
+    │
+    ▼
+[Text Cleaner] ─── Removes noise (markers, page numbers, artifacts)
+    │
+    ▼
+[Confidence Scorer] ─── Flags low-confidence extractions
+    │
+    ├── High confidence (≥0.95) → Direct output
+    │
+    └── Low confidence (<0.95) → [LLM Validator] → Output
+```
+
+## Implementation
+
+### 1. Regex Parser (Handles the Majority)
+
+```python
+import re
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class ParsedItem:
+    id: str
+    text: str
+    choices: tuple[str, ...]
+    answer: str
+    confidence: float = 1.0
+
+def parse_structured_text(content: str) -> list[ParsedItem]:
+    """Parse structured text using regex patterns."""
+    pattern = re.compile(
+        r"(?P<id>\d+)\.\s*(?P<text>.+?)\n"
+        r"(?P<choices>(?:[A-D]\..+?\n)+)"
+        r"Answer:\s*(?P<answer>[A-D])",
+        re.MULTILINE | re.DOTALL,
+    )
+    items = []
+    for match in pattern.finditer(content):
+        choices = tuple(
+            c.strip() for c in re.findall(r"[A-D]\.\s*(.+)", match.group("choices"))
+        )
+        items.append(ParsedItem(
+            id=match.group("id"),
+            text=match.group("text").strip(),
+            choices=choices,
+            answer=match.group("answer"),
+        ))
+    return items
+```
+
+### 2. Confidence Scoring
+
+Flag items that may need LLM review:
+
+```python
+@dataclass(frozen=True)
+class ConfidenceFlag:
+    item_id: str
+    score: float
+    reasons: tuple[str, ...]
+
+def score_confidence(item: ParsedItem) -> ConfidenceFlag:
+    """Score extraction confidence and flag issues."""
+    reasons = []
+    score = 1.0
+
+    if len(item.choices) < 3:
+        reasons.append("few_choices")
+        score -= 0.3
+
+    if not item.answer:
+        reasons.append("missing_answer")
+        score -= 0.5
+
+    if len(item.text) < 10:
+        reasons.append("short_text")
+        score -= 0.2
+
+    return ConfidenceFlag(
+        item_id=item.id,
+        score=max(0.0, score),
+        reasons=tuple(reasons),
+    )
+
+def identify_low_confidence(
+    items: list[ParsedItem],
+    threshold: float = 0.95,
+) -> list[ConfidenceFlag]:
+    """Return items below confidence threshold."""
+    flags = [score_confidence(item) for item in items]
+    return [f for f in flags if f.score < threshold]
+```
+
+### 3. LLM Validator (Edge Cases Only)
+
+```python
+def validate_with_llm(
+    item: ParsedItem,
+    original_text: str,
+    client,
+) -> ParsedItem:
+    """Use LLM to fix low-confidence extractions."""
+    response = client.messages.create(
+        model="claude-haiku-4-5-20251001",  # Cheapest model for validation
+        max_tokens=500,
+        messages=[{
+            "role": "user",
+            "content": (
+                f"Extract the question, choices, and answer from this text.\n\n"
+                f"Text: {original_text}\n\n"
+                f"Current extraction: {item}\n\n"
+                f"Return corrected JSON if needed, or 'CORRECT' if accurate."
+            ),
+        }],
+    )
+    # Parse LLM response and return corrected item...
+    return corrected_item
+```
+
+### 4. Hybrid Pipeline
+
+```python
+def process_document(
+    content: str,
+    *,
+    llm_client=None,
+    confidence_threshold: float = 0.95,
+) -> list[ParsedItem]:
+    """Full pipeline: regex -> confidence check -> LLM for edge cases."""
+    # Step 1: Regex extraction (handles 95-98%)
+    items = parse_structured_text(content)
+
+    # Step 2: Confidence scoring
+    low_confidence = identify_low_confidence(items, confidence_threshold)
+
+    if not low_confidence or llm_client is None:
+        return items
+
+    # Step 3: LLM validation (only for flagged items)
+    low_conf_ids = {f.item_id for f in low_confidence}
+    result = []
+    for item in items:
+        if item.id in low_conf_ids:
+            result.append(validate_with_llm(item, content, llm_client))
+        else:
+            result.append(item)
+
+    return result
+```
+
+## Real-World Metrics
+
+From a production quiz parsing pipeline (410 items):
+
+| Metric | Value |
+|--------|-------|
+| Regex success rate | 98.0% |
+| Low confidence items | 8 (2.0%) |
+| LLM calls needed | ~5 |
+| Cost savings vs all-LLM | ~95% |
+| Test coverage | 93% |
+
+## Best Practices
+
+- **Start with regex** — even imperfect regex gives you a baseline to improve
+- **Use confidence scoring** to programmatically identify what needs LLM help
+- **Use the cheapest LLM** for validation (Haiku-class models are sufficient)
+- **Never mutate** parsed items — return new instances from cleaning/validation steps
+- **TDD works well** for parsers — write tests for known patterns first, then edge cases
+- **Log metrics** (regex success rate, LLM call count) to track pipeline health
+
+## Anti-Patterns to Avoid
+
+- Sending all text to an LLM when regex handles 95%+ of cases (expensive and slow)
+- Using regex for free-form, highly variable text (LLM is better here)
+- Skipping confidence scoring and hoping regex "just works"
+- Mutating parsed objects during cleaning/validation steps
+- Not testing edge cases (malformed input, missing fields, encoding issues)
+
+## When to Use
+
+- Quiz/exam question parsing
+- Form data extraction
+- Invoice/receipt processing
+- Document structure parsing (headers, sections, tables)
+- Any structured text with repeating patterns where cost matters