loki-mode 4.2.0

package/skills/00-index.md

@@ -0,0 +1,120 @@
+# Skill Modules Index
+
+**Load 1-3 modules based on your current task. Do not load all modules.**
+
+> **Full documentation:** For comprehensive details, see `references/` directory:
+> - `references/agents.md` - Complete 37 agent type specifications
+> - `references/openai-patterns.md` - OpenAI Agents SDK patterns
+> - `references/lab-research-patterns.md` - DeepMind + Anthropic research
+> - `references/production-patterns.md` - HN 2025 production insights
+> - `references/memory-system.md` - Episodic/semantic/procedural memory
+> - `references/tool-orchestration.md` - NVIDIA ToolOrchestra efficiency metrics
+> - `references/quality-control.md` - Code review and guardrails
+
+## Module Selection Rules
+
+| If your task involves... | Load these modules |
+|--------------------------|-------------------|
+| Writing code, implementing features | `model-selection.md` |
+| Running tests, E2E, Playwright | `testing.md` |
+| Code review, quality checks | `quality-gates.md` |
+| Deployment, CI/CD, infrastructure | `production.md` |
+| Debugging, errors, failures | `troubleshooting.md` |
+| Spawning subagents, Task tool | `model-selection.md`, `agents.md` |
+| Architecture, design decisions | `patterns-advanced.md` |
+| Generating artifacts, reports | `artifacts.md` |
+| Parallel features, git worktrees | `parallel-workflows.md` |
+| Scale patterns (50+ agents) | `parallel-workflows.md` + `references/cursor-learnings.md` |
+| GitHub issues, PRs, syncing | `github-integration.md` |
+
+## Module Descriptions
+
+### model-selection.md
+**When:** Spawning subagents, choosing models, parallelization
+- Task tool parameters and examples
+- Opus/Sonnet/Haiku usage patterns
+- Extended thinking mode prefixes
+- Prompt repetition for Haiku
+- Background agents and resumption
+
+### quality-gates.md
+**When:** Code review, pre-commit checks, quality assurance
+- 7-gate quality system
+- Blind review + anti-sycophancy
+- Velocity-quality feedback loop (arXiv research)
+- Mandatory quality checks per task
+- Guardrails (input/output validation)
+
+### patterns-advanced.md
+**When:** Architecture decisions, complex problem-solving
+- OptiMind problem classification + expert hints
+- Ensemble solution generation
+- Formal state machines (k8s-valkey-operator)
+- Constitutional AI self-critique
+- Debate-based verification (DeepMind)
+
+### testing.md
+**When:** Writing tests, E2E automation, verification
+- Playwright MCP for browser testing
+- Property-based testing (Kiro pattern)
+- Unit/integration/E2E strategies
+- Visual design input workflow
+
+### production.md
+**When:** Deployment, CI/CD, production concerns
+- HN 2025 production patterns
+- Narrow scope, confidence-based routing
+- Git worktree isolation (Cursor pattern)
+- Atomic checkpoint/rollback
+- CI/CD automation (Zencoder patterns)
+- Context engineering and proactive compaction
+
+### troubleshooting.md
+**When:** Errors, failures, debugging
+- Common issues and solutions
+- Red flags (never do these)
+- Multi-tiered fallback system
+- Rate limit handling
+- Circuit breakers
+
+### agents.md
+**When:** Understanding agent types, structured prompting
+- 37 agent type overview
+- Structured prompting format (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)
+- Agent handoffs and callbacks
+- Routing mode optimization
+
+### artifacts.md
+**When:** Generating reports, documentation, screenshots
+- Artifact generation (Antigravity pattern)
+- Code transformation (Amazon Q pattern)
+- Phase completion reports
+- Screenshot gallery generation
+
+### parallel-workflows.md
+**When:** Running multiple features in parallel, worktree orchestration
+- Git worktree-based isolation
+- Parallel Claude sessions (feature, testing, docs streams)
+- Inter-stream communication via signals
+- Auto-merge completed features
+- Orchestrator state management
+
+### github-integration.md (v4.1.0)
+**When:** Working with GitHub issues, creating PRs, syncing status
+- Import open issues as pending tasks
+- Create PRs on feature completion
+- Sync task status back to GitHub issues
+- Filter by labels, milestone, assignee
+- Requires `gh` CLI authenticated
+
+## How to Load
+
+```python
+# Example: Before implementing a feature with tests
+# 1. Read this index
+# 2. Decide: need model-selection.md + testing.md
+# 3. Read those files
+# 4. Execute with loaded context
+```
+
+**Remember:** Loading fewer modules = more context for actual work.

package/skills/agents.md

@@ -0,0 +1,249 @@
+# Agent Dispatch & Structured Prompting
+
+> **Full agent type definitions:** See `references/agents.md` for complete 37 agent role specifications across 7 swarms (Engineering, Operations, Business, Data, Product, Growth, Review).
+
+---
+
+## How Agents Actually Work
+
+**Claude Code's Task tool has these subagent_types:**
+- `general-purpose` - Most work (implementation, review, testing)
+- `Explore` - Codebase exploration and search
+- `Plan` - Architecture and planning
+- `Bash` - Command execution
+- `platform-orchestrator` - Deployment and service management
+
+**The 37 agent types are ROLES defined through prompts.** Create specialized behavior:
+
+```python
+# Security reviewer = general-purpose + security-focused prompt
+Task(
+    subagent_type="general-purpose",
+    model="opus",
+    description="Security review: auth module",
+    prompt="""You are a security reviewer. Focus on:
+    - Authentication vulnerabilities
+    - Input validation gaps
+    - OWASP Top 10 issues
+    Review: src/auth/*.ts"""
+)
+
+# Frontend agent = general-purpose + frontend-focused prompt
+Task(
+    subagent_type="general-purpose",
+    model="opus",
+    description="Implement login form",
+    prompt="""You are a frontend developer. Implement:
+    - React login form component
+    - Form validation
+    - Error state handling"""
+)
+```
+
+---
+
+## Structured Prompting Template
+
+**Every Task dispatch MUST include these sections:**
+
+```
+## GOAL
+[What success looks like - measurable outcome]
+
+## CONSTRAINTS
+[Hard limits - what you cannot do]
+
+## CONTEXT
+[Files to read, previous attempts, related decisions]
+
+## OUTPUT
+[Exact deliverables expected]
+```
+
+**Example:**
+```python
+Task(
+    subagent_type="general-purpose",
+    model="opus",
+    description="Implement user registration API",
+    prompt="""
+## GOAL
+Create POST /api/users endpoint that registers new users.
+Success: Endpoint works, tests pass, matches OpenAPI spec.
+
+## CONSTRAINTS
+- Use bcrypt for password hashing (already in dependencies)
+- No new dependencies without approval
+- Response time < 200ms
+
+## CONTEXT
+- Existing auth pattern: src/auth/login.ts
+- OpenAPI spec: .loki/specs/openapi.yaml
+- User model: src/models/user.ts
+
+## OUTPUT
+- [ ] Endpoint implementation in src/routes/users.ts
+- [ ] Unit tests in tests/users.test.ts
+- [ ] Integration test in tests/integration/users.test.ts
+"""
+)
+```
+
+---
+
+## Parallel Review Pattern
+
+**Code review uses 3 parallel reviewers with different focus areas:**
+
+```python
+# Launch all 3 in ONE message (parallel execution)
+Task(
+    subagent_type="general-purpose",
+    model="opus",
+    description="Review: correctness",
+    prompt="Review for bugs, logic errors, edge cases. Files: {files}"
+)
+Task(
+    subagent_type="general-purpose",
+    model="opus",
+    description="Review: security",
+    prompt="Review for vulnerabilities, injection, auth issues. Files: {files}"
+)
+Task(
+    subagent_type="general-purpose",
+    model="opus",
+    description="Review: performance",
+    prompt="Review for N+1 queries, memory leaks, slow operations. Files: {files}"
+)
+```
+
+**Rules:**
+- ALWAYS use opus for reviews
+- ALWAYS launch all 3 in single message
+- WAIT for all 3 before aggregating
+- IF unanimous approval: run Devil's Advocate reviewer
+
+---
+
+## Confidence-Based Routing
+
+| Confidence | Dispatch Strategy |
+|------------|-------------------|
+| >= 0.95 | Direct haiku execution, no review |
+| 0.70-0.95 | Direct execution + async review |
+| 0.40-0.70 | Supervisor orchestration, mandatory review |
+| < 0.40 | Flag for human decision |
+
+**Confidence factors:**
+- Requirement clarity (30%)
+- Similar past successes (20%)
+- Technical complexity match (25%)
+- Resource availability (15%)
+- Time pressure (10%)
+
+---
+
+## Agent Handoffs
+
+When one agent completes and hands off to another:
+
+```python
+# Agent A completes, hands off to Agent B
+handoff_data = {
+    "completed_work": "Implemented user registration endpoint",
+    "files_modified": ["src/routes/users.ts", "tests/users.test.ts"],
+    "decisions_made": ["Used bcrypt, not argon2", "Email validation via regex"],
+    "open_questions": ["Rate limiting not implemented yet"],
+    "mistakes_learned": ["First attempt had SQL injection - fixed"]
+}
+
+Task(
+    subagent_type="general-purpose",
+    model="sonnet",
+    description="Integration testing for user registration",
+    prompt=f"Previous agent completed: {handoff_data}. Now write integration tests..."
+)
+```
+
+---
+
+## Project AGENTS.md
+
+**IF target project has AGENTS.md, read it first.** (OpenAI/AAIF standard)
+
+Priority order for context:
+1. `AGENTS.md` in current directory
+2. `CLAUDE.md` project instructions
+3. `.loki/CONTINUITY.md` session state
+
+---
+
+## A2A-Inspired Communication (Google Protocol)
+
+**Agent Cards for capability discovery:**
+
+```json
+{
+  "agent_id": "eng-backend-001",
+  "capabilities": ["api-endpoint", "auth", "database"],
+  "status": "available",
+  "current_task": null,
+  "inbox": ".loki/messages/inbox/eng-backend-001/",
+  "outbox": ".loki/messages/outbox/eng-backend-001/"
+}
+```
+
+**Handoff message format:**
+
+```json
+{
+  "from": "eng-backend-001",
+  "to": "eng-qa-001",
+  "task_id": "task-123",
+  "type": "handoff",
+  "payload": {
+    "completed_work": "POST /api/users implemented",
+    "files_modified": ["src/routes/users.ts"],
+    "decisions": ["bcrypt for passwords"],
+    "artifacts": [".loki/artifacts/users-api-spec.json"]
+  }
+}
+```
+
+**Location:** `.loki/messages/` directory structure
+
+---
+
+## Agentic Patterns Reference (awesome-agentic-patterns)
+
+**Patterns used in Loki Mode:**
+
+| Pattern | Implementation |
+|---------|---------------|
+| Sub-Agent Spawning | Task tool with focused prompts |
+| Plan-Then-Execute | Architect -> Engineer workflow |
+| Dual LLM | Opus for planning, Haiku for execution |
+| CI Feedback Loop | Test results injected into retry prompts |
+| Self-Critique | Constitutional AI revision cycle |
+| Semantic Context Filtering | Only relevant files in context |
+| Episodic Memory | `.loki/memory/episodic/` traces |
+
+**Key insight (moridinamael.github.io):** Simple orchestration beats complex frameworks. "Ralph Wiggum Mode" - basic continuation prompts work better than elaborate coordination systems.
+
+---
+
+## The 37 Agent Roles
+
+See `references/agents.md` for complete specifications. Summary:
+
+| Swarm | Agent Types | Count |
+|-------|-------------|-------|
+| Engineering | frontend, backend, database, mobile, api, qa, perf, infra | 8 |
+| Operations | devops, sre, security, monitor, incident, release, cost, compliance | 8 |
+| Business | marketing, sales, finance, legal, support, hr, investor, partnerships | 8 |
+| Data | ml, eng, analytics | 3 |
+| Product | pm, design, techwriter | 3 |
+| Growth | hacker, community, success, lifecycle | 4 |
+| Review | code, business, security | 3 |
+
+**Spawn only what you need.** Simple project: 5-10 agents. Complex startup: 100+.

package/skills/artifacts.md

@@ -0,0 +1,174 @@
+# Artifact Generation & Code Transformation
+
+## Artifact Generation (Antigravity Pattern)
+
+**Auto-generate verifiable deliverables for audit trail without human intervention.**
+
+```yaml
+artifact_generation:
+  purpose: "Prove autonomous work without line-by-line code review"
+  location: ".loki/artifacts/{date}/{phase}/"
+
+  triggers:
+    on_phase_complete:
+      - verification_report: "Summary of tests passed, coverage, static analysis"
+      - architecture_diff: "Mermaid diagram showing changes from previous state"
+      - decision_log: "Key decisions made with rationale (from CONTINUITY.md)"
+
+    on_feature_complete:
+      - screenshot: "Key UI states captured via Playwright"
+      - api_diff: "OpenAPI spec changes highlighted"
+      - test_summary: "Unit, integration, E2E results"
+
+    on_deployment:
+      - release_notes: "Auto-generated from commit history"
+      - rollback_plan: "Steps to revert if issues detected"
+      - monitoring_baseline: "Expected metrics post-deploy"
+```
+
+---
+
+## Artifact Types
+
+### Verification Report
+```yaml
+format: "markdown"
+contents:
+  - Phase name and duration
+  - Tasks completed (from queue)
+  - Quality gate results (7 gates)
+  - Coverage metrics
+  - Known issues / TODOs
+```
+
+### Architecture Diff
+```yaml
+format: "mermaid diagram"
+contents:
+  - Components added/modified/removed
+  - Dependency changes
+  - Data flow changes
+```
+
+### Screenshot Gallery
+```yaml
+format: "png + markdown index"
+capture:
+  - Critical user flows
+  - Error states
+  - Before/after comparisons
+```
+
+**Why artifacts matter for autonomous operation:**
+- Creates audit trail without human during execution
+- Enables async human review if needed later
+- Proves work quality through outcomes, not code inspection
+- Aligns with "outcome verification" over "line-by-line auditing"
+
+---
+
+## Code Transformation Agent (Amazon Q Pattern)
+
+**Dedicated workflows for legacy modernization - narrow scope, deterministic verification.**
+
+```yaml
+transformation_agent:
+  purpose: "Autonomous code migration without human intervention"
+  trigger: "/transform or PRD mentions migration/upgrade/modernization"
+
+  workflows:
+    language_upgrade:
+      steps:
+        1. Analyze current version and dependencies
+        2. Identify deprecated APIs and breaking changes
+        3. Generate migration plan with risk assessment
+        4. Apply transformations incrementally
+        5. Run compatibility tests after each change
+        6. Validate performance benchmarks
+      examples:
+        - "Java 8 to Java 21"
+        - "Python 2 to Python 3"
+        - "Node 16 to Node 22"
+
+    database_migration:
+      steps:
+        1. Schema diff analysis (source vs target)
+        2. SQL dialect conversion rules
+        3. Data type mapping
+        4. Generate migration scripts
+        5. Run verification queries
+        6. Validate data integrity
+      examples:
+        - "Oracle to PostgreSQL"
+        - "MySQL to PostgreSQL"
+        - "MongoDB to PostgreSQL"
+
+    framework_modernization:
+      steps:
+        1. Dependency audit and compatibility matrix
+        2. Breaking change detection
+        3. Code pattern updates (deprecated -> modern)
+        4. Test suite adaptation
+        5. Performance regression testing
+      examples:
+        - "Angular to React"
+        - ".NET Framework to .NET Core"
+        - "Express to Fastify"
+
+  success_criteria:
+    - All existing tests pass
+    - No regression in performance (< 5% degradation)
+    - Static analysis clean
+    - API compatibility maintained (or documented breaks)
+```
+
+**Why this fits autonomous operation:**
+- Narrow scope with clear boundaries
+- Deterministic success criteria (tests pass, benchmarks met)
+- No subjective judgment required
+- High value, repetitive tasks
+
+---
+
+## Code-Only Agent Pattern (rijnard.com)
+
+**Enforce execution through code, creating verifiable "code witnesses".**
+
+```yaml
+code_only_principle:
+  benefit: "Produces executable, verifiable behavior traces"
+
+  patterns:
+    - Return small outputs (<1KB) inline
+    - Write large results to JSON files with path references
+    - Use dynamic languages (Python, TypeScript) for native runtime injection
+
+  enforcement:
+    - Tool PreHooks to catch banned operations
+    - Initial prompting toward code-generation patterns
+```
+
+**Key Insight:** LLM outputs should be executable code, not prose descriptions. This creates an auditable trace of what actually happened.
+
+---
+
+## Release Notes Generation
+
+**Auto-generate from commit history:**
+
+```bash
+# Generate release notes from git commits
+git log --oneline v2.0.0..HEAD | \
+  grep -E "^[a-f0-9]+ (feat|fix|perf|refactor):" | \
+  sed 's/^[a-f0-9]* /- /'
+```
+
+```yaml
+release_notes_template:
+  sections:
+    - "## New Features" (feat: commits)
+    - "## Bug Fixes" (fix: commits)
+    - "## Performance" (perf: commits)
+    - "## Breaking Changes" (BREAKING: in commit body)
+    - "## Migration Guide" (if breaking changes)
+```