loki-mode 4.2.0

package/skills/production.md

@@ -0,0 +1,292 @@
+# Production Patterns
+
+## HN 2025 Battle-Tested Patterns
+
+### Narrow Scope Wins
+
+```yaml
+task_constraints:
+  max_steps_before_review: 3-5
+  characteristics:
+    - Specific, well-defined objectives
+    - Pre-classified inputs
+    - Deterministic success criteria
+    - Verifiable outputs
+```
+
+### Deterministic Outer Loops
+
+**Wrap agent outputs with rule-based validation (NOT LLM-judged):**
+
+```
+1. Agent generates output
+2. Run linter (deterministic)
+3. Run tests (deterministic)
+4. Check compilation (deterministic)
+5. Only then: human or AI review
+```
+
+### Context Engineering
+
+```yaml
+principles:
+  - "Less is more" - focused beats comprehensive
+  - Manual selection outperforms automatic RAG
+  - Fresh conversations per major task
+  - Remove outdated information aggressively
+
+context_budget:
+  target: "< 10k tokens for context"
+  reserve: "90% for model reasoning"
+```
+
+---
+
+## Proactive Context Management (OpenCode Pattern)
+
+**Prevent context overflow in long autonomous sessions:**
+
+```yaml
+compaction_strategy:
+  trigger: "Every 25 iterations OR context feels heavy"
+
+  preserve_always:
+    - CONTINUITY.md content (current state)
+    - Current task specification
+    - Recent Mistakes & Learnings (last 5)
+    - Active queue items
+
+  consolidate:
+    - Completed task summaries -> semantic memory
+    - Resolved errors -> anti-patterns
+    - Successful patterns -> procedural memory
+
+  discard:
+    - Verbose tool outputs
+    - Intermediate reasoning
+    - Superseded plans
+```
+
+---
+
+## Sub-Agents for Context Isolation
+
+**Run expensive explorations in isolated contexts:**
+
+```python
+# Heavy analysis that would bloat main context
+Task(
+    subagent_type="Explore",
+    model="haiku",
+    description="Find all auth-related files",
+    prompt="Search codebase for authentication patterns. Return only file paths."
+)
+# Main context stays clean; only results return
+```
+
+---
+
+## Git Worktree Isolation (Cursor Pattern)
+
+**Use git worktrees for parallel implementation agents:**
+
+```bash
+# Create isolated worktree for feature
+git worktree add ../project-feature-auth feature/auth
+
+# Agent works in isolated worktree
+cd ../project-feature-auth
+# ... implement feature ...
+
+# Merge back when complete
+git checkout main
+git merge feature/auth
+git worktree remove ../project-feature-auth
+```
+
+**Benefits:**
+- Multiple agents can work in parallel without conflicts
+- Each agent has clean, isolated file state
+- Merges happen explicitly, not through file racing
+
+---
+
+## Atomic Checkpoint/Rollback (Cursor Pattern)
+
+```yaml
+checkpoint_strategy:
+  when:
+    - Before spawning any subagent
+    - Before any destructive operation
+    - After completing a task successfully
+
+  how:
+    - git commit -m "CHECKPOINT: before {operation}"
+    - Record commit hash in CONTINUITY.md
+
+  rollback:
+    - git reset --hard {checkpoint_hash}
+    - Update CONTINUITY.md with rollback reason
+    - Add to Mistakes & Learnings
+```
+
+---
+
+## CI/CD Automation (Zencoder Patterns)
+
+### CI Failure Analysis and Auto-Resolution
+
+```yaml
+ci_failure_workflow:
+  1. Detect CI failure (webhook or poll)
+  2. Parse error logs for root cause
+  3. Classify failure type:
+     - Test failure: Fix code, re-run tests
+     - Lint failure: Auto-fix with --fix flag
+     - Build failure: Check dependencies, configs
+     - Flaky test: Mark and investigate separately
+  4. Apply fix and push
+  5. Monitor CI result
+  6. If still failing after 3 attempts: escalate
+```
+
+### Automated Review Comment Resolution
+
+```yaml
+pr_comment_workflow:
+  trigger: "New review comment on PR"
+
+  workflow:
+    1. Parse comment for actionable feedback
+    2. Classify: bug, style, question, suggestion
+    3. For bugs/style: implement fix
+    4. For questions: add code comment or respond
+    5. For suggestions: evaluate and implement if beneficial
+    6. Push changes and mark comment resolved
+```
+
+### Continuous Dependency Management
+
+```yaml
+dependency_workflow:
+  schedule: "Weekly or on security advisory"
+
+  workflow:
+    1. Run npm audit / pip-audit / cargo audit
+    2. Classify vulnerabilities by severity
+    3. For Critical/High: immediate update
+    4. For Medium: schedule update
+    5. Run full test suite after updates
+    6. Create PR with changelog
+```
+
+---
+
+## Batch Processing (Claude API)
+
+**50% cost reduction for large-scale async operations.**
+
+### When to Use Batch API
+
+| Use Case | Batch? | Reasoning |
+|----------|--------|-----------|
+| Single code review | No | Immediate feedback needed |
+| Review 100+ files | Yes | 50% savings, async OK |
+| Generate tests for all modules | Yes | Bulk operation |
+| Interactive development | No | Need real-time responses |
+| Large-scale evaluations | Yes | Cost-critical at scale |
+| QA phase bulk analysis | Yes | Can wait for results |
+
+### Batch API Limits
+
+```yaml
+limits:
+  max_requests: 100,000 per batch
+  max_size: 256 MB per batch
+  processing_time: Most < 1 hour (max 24h)
+  results_available: 29 days
+
+pricing:
+  discount: 50% on all tokens
+  stacks_with: Prompt caching (30-98% cache hits)
+```
+
+### Implementation Pattern
+
+```python
+import anthropic
+from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
+from anthropic.types.messages.batch_create_params import Request
+
+client = anthropic.Anthropic()
+
+# Batch all code review requests
+def batch_code_review(files: list[str]) -> str:
+    requests = [
+        Request(
+            custom_id=f"review-{i}-{file.replace('/', '-')}",
+            params=MessageCreateParamsNonStreaming(
+                model="claude-sonnet-4-5",
+                max_tokens=2048,
+                messages=[{
+                    "role": "user",
+                    "content": f"Review this code for bugs, security, performance:\n\n{open(file).read()}"
+                }]
+            )
+        )
+        for i, file in enumerate(files)
+    ]
+
+    batch = client.messages.batches.create(requests=requests)
+    return batch.id  # Poll for results later
+
+# Poll for completion
+def wait_for_batch(batch_id: str):
+    while True:
+        batch = client.messages.batches.retrieve(batch_id)
+        if batch.processing_status == "ended":
+            return batch
+        time.sleep(60)
+
+# Stream results
+def process_results(batch_id: str):
+    for result in client.messages.batches.results(batch_id):
+        if result.result.type == "succeeded":
+            # Process successful review
+            handle_review(result.custom_id, result.result.message)
+        elif result.result.type == "errored":
+            # Retry or log error
+            handle_error(result.custom_id, result.result.error)
+```
+
+### Batch + Prompt Caching
+
+**Stack discounts for maximum savings:**
+
+```python
+# All requests share cached system prompt
+SHARED_SYSTEM = [
+    {"type": "text", "text": "You are a code reviewer..."},
+    {"type": "text", "text": CODING_STANDARDS,  # Large shared context
+     "cache_control": {"type": "ephemeral"}}
+]
+
+requests = [
+    Request(
+        custom_id=f"review-{file}",
+        params=MessageCreateParamsNonStreaming(
+            model="claude-sonnet-4-5",
+            max_tokens=2048,
+            system=SHARED_SYSTEM,  # Identical across all requests
+            messages=[{"role": "user", "content": f"Review: {code}"}]
+        )
+    )
+    for file, code in files_with_code
+]
+```
+
+**Cost math:**
+- Base: $3/MTok input, $15/MTok output (Sonnet)
+- Batch discount: 50% -> $1.50/$7.50
+- Cache hit: 90% reduction on cached tokens
+- Combined: Up to 95% savings on large batches

package/skills/quality-gates.md

@@ -0,0 +1,180 @@
+# Quality Gates
+
+**Never ship code without passing all quality gates.**
+
+## The 7 Quality Gates
+
+1. **Input Guardrails** - Validate scope, detect injection, check constraints (OpenAI SDK)
+2. **Static Analysis** - CodeQL, ESLint/Pylint, type checking
+3. **Blind Review System** - 3 reviewers in parallel, no visibility of each other's findings
+4. **Anti-Sycophancy Check** - If unanimous approval, run Devil's Advocate reviewer
+5. **Output Guardrails** - Validate code quality, spec compliance, no secrets (tripwire on fail)
+6. **Severity-Based Blocking** - Critical/High/Medium = BLOCK; Low/Cosmetic = TODO comment
+7. **Test Coverage Gates** - Unit: 100% pass, >80% coverage; Integration: 100% pass
+
+## Guardrails Execution Modes
+
+- **Blocking**: Guardrail completes before agent starts (use for expensive operations)
+- **Parallel**: Guardrail runs with agent (use for fast checks, accept token loss risk)
+
+**Research:** Blind review + Devil's Advocate reduces false positives by 30% (CONSENSAGENT, 2025)
+
+---
+
+## Velocity-Quality Feedback Loop (CRITICAL)
+
+**Research from arXiv 2511.04427v2 - empirical study of 807 repositories.**
+
+### Key Findings
+
+| Metric | Finding | Implication |
+|--------|---------|-------------|
+| Initial Velocity | +281% lines added | Impressive but TRANSIENT |
+| Quality Degradation | +30% static warnings, +41% complexity | PERSISTENT problem |
+| Cancellation Point | 3.28x complexity OR 4.94x warnings | Completely negates velocity gains |
+
+### The Trap to Avoid
+
+```
+Initial excitement -> Velocity spike -> Quality degradation accumulates
+                                               |
+                                               v
+                               Complexity cancels velocity gains
+                                               |
+                                               v
+                               Frustration -> Abandonment cycle
+```
+
+**CRITICAL RULE:** Every velocity gain MUST be accompanied by quality verification.
+
+### Mandatory Quality Checks (Per Task)
+
+```yaml
+velocity_quality_balance:
+  before_commit:
+    - static_analysis: "Run ESLint/Pylint/CodeQL - warnings must not increase"
+    - complexity_check: "Cyclomatic complexity must not increase >10%"
+    - test_coverage: "Coverage must not decrease"
+
+  thresholds:
+    max_new_warnings: 0  # Zero tolerance for new warnings
+    max_complexity_increase: 10%  # Per file, per commit
+    min_coverage: 80%  # Never drop below
+
+  if_threshold_violated:
+    action: "BLOCK commit, fix before proceeding"
+    reason: "Velocity gains without quality are net negative"
+```
+
+### Metrics to Track
+
+```
+.loki/metrics/quality/
++-- warnings.json      # Static analysis warning count over time
++-- complexity.json    # Cyclomatic complexity per file
++-- coverage.json      # Test coverage percentage
++-- velocity.json      # Lines added/commits per hour
++-- ratio.json         # Quality/Velocity ratio (must stay positive)
+```
+
+---
+
+## Blind Review System
+
+**Launch 3 reviewers in parallel in a single message:**
+
+```python
+# ALWAYS launch all 3 in ONE message
+Task(model="sonnet", description="Code review: correctness", prompt="Review for bugs...")
+Task(model="sonnet", description="Code review: security", prompt="Review for vulnerabilities...")
+Task(model="sonnet", description="Code review: performance", prompt="Review for efficiency...")
+```
+
+**Rules:**
+- ALWAYS use sonnet for reviews (balanced quality/cost)
+- NEVER aggregate before all 3 complete
+- ALWAYS re-run ALL 3 after fixes
+- If unanimous approval -> run Devil's Advocate
+
+---
+
+## Severity-Based Blocking
+
+| Severity | Action |
+|----------|--------|
+| Critical | BLOCK - fix immediately |
+| High | BLOCK - fix before commit |
+| Medium | BLOCK - fix before merge |
+| Low | TODO comment, fix later |
+| Cosmetic | Note, optional fix |
+
+See `references/quality-control.md` for complete details.
+
+---
+
+## Scale Considerations
+
+> **Source:** [Cursor Scaling Learnings](../references/cursor-learnings.md) - integrators became bottlenecks at 100+ agents
+
+### Review Intensity Scaling
+
+At high agent counts, full 3-reviewer blind review for every change creates bottlenecks.
+
+```yaml
+review_scaling:
+  low_scale:  # <10 agents
+    all_changes: "Full 3-reviewer blind review"
+    rationale: "Quality critical, throughput acceptable"
+
+  medium_scale:  # 10-50 agents
+    high_risk: "Full 3-reviewer blind review"
+    medium_risk: "2-reviewer review"
+    low_risk: "1 reviewer + automated checks"
+    rationale: "Balance quality and throughput"
+
+  high_scale:  # 50+ agents
+    critical_changes: "Full 3-reviewer blind review"
+    standard_changes: "Automated checks + spot review"
+    trivial_changes: "Automated checks only"
+    rationale: "Trust workers, avoid bottlenecks"
+
+risk_classification:
+  high_risk:
+    - Security-related changes
+    - Authentication/authorization
+    - Payment processing
+    - Data migrations
+    - API breaking changes
+  medium_risk:
+    - New features
+    - Business logic changes
+    - Database schema changes
+  low_risk:
+    - Bug fixes with tests
+    - Refactoring with no behavior change
+    - Documentation
+    - Dependency updates (minor)
+```
+
+### Judge Agent Integration
+
+Use judge agents to determine when full review is needed:
+
+```yaml
+judge_review_decision:
+  inputs:
+    - change_type: "feature|bugfix|refactor|docs"
+    - files_changed: 5
+    - lines_changed: 120
+    - test_coverage: 85%
+    - static_analysis: "0 new warnings"
+  output:
+    review_level: "full|partial|automated"
+    rationale: "Medium-risk feature with good coverage"
+```
+
+### Cursor's Key Learning
+
+> "Dedicated integrator/reviewer roles created more bottlenecks than they solved. Workers were already capable of handling conflicts themselves."
+
+**Implication:** At scale, trust automated checks and worker judgment. Reserve full review for high-risk changes only.

package/skills/testing.md

@@ -0,0 +1,149 @@
+# Testing
+
+## E2E Testing with Playwright MCP
+
+**Use Playwright MCP for browser-based testing.**
+
+```python
+# E2E test after feature implementation
+Task(
+    subagent_type="general-purpose",
+    model="sonnet",
+    description="Run E2E tests for auth flow",
+    prompt="""Use Playwright MCP to test:
+    1. Navigate to /login
+    2. Fill email and password fields
+    3. Click submit button
+    4. Verify redirect to /dashboard
+    5. Check user name appears in header
+
+    Use accessibility tree refs, not coordinates."""
+)
+```
+
+**Best Practices:**
+- Use accessibility tree refs instead of coordinates
+- Test critical user flows after each feature
+- Capture screenshots for error states
+- Run after unit tests, before deployment
+
+---
+
+## Property-Based Testing (Kiro Pattern)
+
+**Auto-generate edge case tests from specifications.**
+
+```yaml
+property_based_testing:
+  purpose: "Verify code meets spec constraints with hundreds of random inputs"
+  tools: "fast-check (JS/TS), hypothesis (Python), QuickCheck (Haskell)"
+
+  extract_properties_from:
+    - OpenAPI schema: "minLength, maxLength, pattern, enum, minimum, maximum"
+    - Business rules: "requirements.md invariants"
+    - Data models: "TypeScript interfaces, DB constraints"
+
+  examples:
+    - "email field always matches email regex"
+    - "price is never negative"
+    - "created_at <= updated_at always"
+    - "array length never exceeds maxItems"
+```
+
+**When to use:**
+- After implementing API endpoints (validate against OpenAPI)
+- After data model changes (validate invariants)
+- Before deployment (edge case regression)
+
+---
+
+## Event-Driven Hooks (Kiro Pattern)
+
+**Trigger quality checks on file operations, not just at phase boundaries.**
+
+```yaml
+hooks_system:
+  location: ".loki/hooks/"
+
+  triggers:
+    on_file_write:
+      - lint: "npx eslint --fix {file}"
+      - typecheck: "npx tsc --noEmit"
+      - secrets_scan: "detect-secrets scan {file}"
+
+    on_task_complete:
+      - contract_test: "npm run test:contract"
+      - spec_lint: "spectral lint .loki/specs/openapi.yaml"
+
+    on_phase_complete:
+      - memory_consolidate: "Extract patterns to semantic memory"
+      - metrics_update: "Log efficiency scores"
+      - checkpoint: "git commit with phase summary"
+```
+
+**Benefits:**
+- Catches issues 5-10x earlier than phase-end review
+- Reduces rework cycles
+- Aligns with Constitutional AI (continuous self-critique)
+
+---
+
+## Visual Design Input
+
+**When given design mockups or screenshots:**
+
+1. **Discovery Phase:** Extract visual requirements from mockups
+2. **Development Phase:** Implement UI matching design specs
+3. **QA Phase:** Visual regression testing with Playwright screenshots
+4. **Verification:** Compare screenshots against original designs
+
+```python
+# Capture screenshot for comparison
+Task(
+    model="sonnet",
+    description="Visual regression test",
+    prompt="""Use Playwright MCP to:
+    1. Navigate to implemented feature
+    2. Capture screenshot
+    3. Compare against design mockup at designs/feature.png
+    4. Report visual differences"""
+)
+```
+
+---
+
+## Test Strategy by Phase
+
+| Phase | Test Type | Tool |
+|-------|-----------|------|
+| Development | Unit tests | Haiku (parallel) |
+| Development | Integration tests | Sonnet |
+| QA | E2E tests | Playwright MCP |
+| QA | Property-based tests | fast-check/hypothesis |
+| Pre-deployment | Full regression | All of above |
+
+---
+
+## Review-to-Memory Learning
+
+**Pipe code review findings into semantic memory to prevent repeat mistakes.**
+
+```yaml
+review_learning:
+  trigger: "After every code review cycle"
+
+  workflow:
+    1. Complete 3-reviewer blind review
+    2. Aggregate findings by severity
+    3. For each Critical/High/Medium finding:
+       - Extract pattern description
+       - Document prevention strategy
+       - Save to .loki/memory/semantic/anti-patterns/
+    4. Link to episodic memory for traceability
+
+  output_format:
+    pattern: "Using any instead of proper TypeScript types"
+    category: "type-safety"
+    severity: "high"
+    prevention: "Always define explicit interfaces for API responses"
+```