incitaciones 0.1.0

package/pi-package/skills/multi-agent-review/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: multi-agent-review
+description: "Coordinate multiple agents for comprehensive review"
+metadata:
+  installed-from: "incitaciones"
+---
+I need a comprehensive multi-agent parallel code review using the Wave/Gate architecture.
+
+CODE TO REVIEW:
+[paste code or specify: "Review all files in src/auth/"]
+
+ARCHITECTURE:
+Wave 1 (Parallel) → Gate 1 (Sequential) → Wave 2 (Parallel) → Gate 2 (Sequential) → Wave 3 (Sequential)
+
+Execute this workflow:
+
+═══════════════════════════════════════════════════════════════
+WAVE 1: PARALLEL INDEPENDENT ANALYSIS
+═══════════════════════════════════════════════════════════════
+
+Launch 5 parallel tasks. Each task is independent and can run simultaneously.
+
+TASK 1: Security Review
+Role: Security Engineer
+Focus:
+- OWASP Top 10 vulnerabilities
+- Input validation and sanitization
+- Authentication and authorization flaws
+- SQL injection, XSS, CSRF, SSRF
+- Secret management and data exposure
+- API security and rate limiting
+- Cryptography usage
+
+Output JSON format:
+{
+  "issues": [
+    {
+      "id": "SEC-001",
+      "severity": "CRITICAL|HIGH|MEDIUM|LOW",
+      "category": "authentication|input-validation|data-exposure|cryptography",
+      "cwe_id": "CWE-XXX",
+      "location": "file.js:line",
+      "description": "Detailed description",
+      "attack_vector": "How an attacker could exploit this",
+      "recommendation": "Specific fix with code example"
+    }
+  ],
+  "security_score": 0-3,
+  "summary": "One-line summary"
+}
+
+TASK 2: Performance Review
+Role: Performance Engineer
+Focus:
+- Time complexity (O(n²), O(n³) patterns)
+- Database queries (N+1, missing indexes, full table scans)
+- Memory allocation and leaks
+- Unnecessary loops and iterations
+- Caching opportunities
+- Blocking I/O operations
+- Resource pooling
+
+TASK 3: Maintainability Review
+Role: Future Developer (6 months out, original author gone)
+Focus:
+- Code clarity and readability
+- Documentation (comments, docstrings, README)
+- Pattern consistency across codebase
+- Naming conventions (clear, descriptive)
+- Technical debt indicators
+- DRY violations
+- Magic numbers and hard-coded values
+- Complex conditionals
+
+TASK 4: Requirements Validation
+Role: QA Engineer
+Focus:
+- Requirements coverage (are all requirements implemented?)
+- Edge case handling
+- Test coverage gaps
+- Behavioral correctness
+- Missing functionality
+- Acceptance criteria satisfaction
+
+TASK 5: Operations Review
+Role: SRE (on-call at 3am when this breaks)
+Focus:
+- Failure modes and error handling
+- Observability (logging, metrics, tracing)
+- Timeout and retry logic
+- Circuit breakers and graceful degradation
+- Resource management (connections, files, memory)
+- Deployment/rollback complexity
+- Configuration management
+- Health checks and readiness probes
+
+═══════════════════════════════════════════════════════════════
+GATE 1: CONFLICT RESOLUTION (Wait for all Wave 1 tasks)
+═══════════════════════════════════════════════════════════════
+
+After all 5 tasks complete, consolidate findings:
+
+TASK 6: Consolidation
+Role: Senior Technical Lead
+
+Tasks:
+1. DEDUPLICATE ISSUES
+   - Same issue reported by multiple reviewers → merge
+   - Similar issues → merge if same root cause
+   - Different perspectives on same code → keep separate if addressing different concerns
+
+2. RESOLVE SEVERITY CONFLICTS
+   Rules:
+   - Security CRITICAL always wins
+   - Take highest severity if 2+ reviewers agree it's a problem
+   - Downgrade if only 1 reviewer flagged and others cleared
+
+3. CALCULATE CONFIDENCE
+   - Found by 1 reviewer: confidence = 0.60
+   - Found by 2 reviewers: confidence = 0.80
+   - Found by 3+ reviewers: confidence = 0.95
+   - Severity disagreement: reduce confidence by 0.15
+
+4. IDENTIFY CROSS-CUTTING CONCERNS
+   - Issues affecting multiple domains
+   - Systemic patterns (same problem in multiple places)
+
+═══════════════════════════════════════════════════════════════
+WAVE 2: PARALLEL CROSS-VALIDATION
+═══════════════════════════════════════════════════════════════
+
+Launch 2-3 parallel tasks reviewing the consolidated findings.
+
+TASK 7: Meta-Review
+Role: Quality Control Lead
+
+Check:
+1. COVERAGE GAPS - What wasn't examined?
+2. FALSE POSITIVES - Are flagged issues actually problems?
+3. SEVERITY CALIBRATION - Are CRITICAL ratings actually critical?
+4. REVIEWER QUALITY - Did reviewers follow their focus areas?
+5. SYSTEMIC PATTERNS - Do issues indicate deeper architectural problems?
+
+TASK 8: Integration Analysis
+Role: Systems Architect
+
+Check for:
+- System-wide impacts of issues
+- Cascading failure scenarios
+- Service dependency problems
+- Data flow issues across boundaries
+
+═══════════════════════════════════════════════════════════════
+GATE 2: FINAL SYNTHESIS (Wait for Wave 2)
+═══════════════════════════════════════════════════════════════
+
+TASK 9: Final Report
+
+Generate:
+1. EXECUTIVE SUMMARY
+   - Total issues by severity
+   - Blockers (CRITICAL issues that prevent merge/deploy)
+   - Key systemic issues
+
+2. PRIORITIZED ACTION LIST
+   - Must fix before merge (CRITICAL)
+   - Should fix before deploy (HIGH)
+   - Can fix later (MEDIUM/LOW)
+
+3. BLOCKING ASSESSMENT
+   - BLOCKS MERGE: Has CRITICAL issues
+   - BLOCKS DEPLOY: Has HIGH operational risks
+   - APPROVED: Ready for production
+   - APPROVED_WITH_NOTES: Deploy with monitoring plan
+
+4. CONVERGENCE METRICS
+   - Number of issues found: CRITICAL/HIGH/MEDIUM/LOW
+   - Confidence level: X% high-confidence issues
+   - False positive estimate: X%
+   - Coverage assessment: X% of code reviewed thoroughly
+
+═══════════════════════════════════════════════════════════════
+WAVE 3: CONVERGENCE CHECK
+═══════════════════════════════════════════════════════════════
+
+Determine if another iteration is needed:
+
+CONVERGED if:
+- new_critical_count == 0 AND
+- new_issue_rate < 0.10 AND
+- false_positive_rate < 0.20
+
+ESCALATE_TO_HUMAN if:
+- iteration >= 3 OR
+- Found conflicting CRITICAL issues OR
+- Uncertain about severity
+
+ITERATE if:
+- new_critical_count > 0 OR
+- new_issue_rate >= 0.10
+
+If ITERATE: Start Wave 1 again focusing only on CRITICAL and HIGH issues.

package/pi-package/skills/mutability-diagnostician/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mutability-diagnostician
+description: "Diagnose pathological mutable state, side effect entanglement, and temporal coupling — map findings to immutability refactoring patterns"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- Full version: content/prompt-task-mutability-diagnostician.md -->
+You are a Functional Architecture Analyst. Diagnose pathological mutable state — shared mutation, side effect entanglement, temporal coupling, and missing domain encapsulation — and map each finding to an immutability refactoring pattern. Do NOT modify any files — advisory only.
+
+**GUARD:** Do not apply to greenfield projects, codebases already using functional architecture with isolated side effects, or when the problem is structural coupling/inheritance (use rigidity-diagnostician). Local mutation within pure functions (loop accumulators, builders) is acceptable — only flag mutation that crosses boundaries.
+
+**INPUT**
+- Target files/directory: [SPECIFY]
+- High-churn files (optional): [git log output OR "none"]
+- Architecture reference (optional): [AGENTS.md rules OR "none"]
+- Language/framework (optional): [e.g., "TypeScript/React" — or "infer"]
+
+**PROTOCOL (Five-Step Pipeline)**
+
+Step 1 — Detect Mutability Signals: Read all files. Identify:
+- Shared Mutable State (Critical): fields modified by multiple methods/classes; globals; mutable state across thread/async boundaries
+- Side Effect Entanglement (High): functions mixing I/O (DB, API, file, clock) with business logic in the same method
+- Temporal Coupling (High): methods requiring specific call order; setup-before-use with invalid intermediate states
+- Primitive Obsession (High): domain concepts (money, email, coordinates) as raw strings/numbers without validation
+- Void Mutation Methods (Medium): void return mutating objects in place — callers can't track changes
+- Mutable Variable Overuse (Medium): `let`/`var`/non-final where `const`/`val`/`final`/`readonly` suffices
+- Defensive Copy Absence (Medium): getters returning direct references to internal mutable collections
+- Check-Then-Act Races (High): validation followed by operation assuming state unchanged — concurrent modification risk
+Note file, line range, and description for each.
+
+Step 2 — Classify Mutation Scope: For each signal, assess:
+- Scope: Local (within function) / Object (instance state) / Cross-Object (shared between classes) / Global (singleton/static)
+- Concurrency exposure: multi-threaded shared (Critical) / async shared (High) / single-threaded (Low)
+- Temporal coupling: does correctness depend on call ordering? (High if yes)
+- Test isolation: requires I/O mocking (High) / requires specific setup (Medium) / testable in isolation (Low)
+
+Step 3 — Analyze Side Effect Boundaries: Classify every function as:
+- **Data**: inert values/structures
+- **Calculation**: pure — same inputs always produce same outputs, no side effects
+- **Action**: impure — depends on when/how many times called (network, disk, clock, mutable external state)
+For top 5-10 Actions by severity, identify Calculations trapped inside: business logic lines interleaved with I/O. Map which lines are Actions vs Calculations.
+
+Step 4 — Map to Refactoring Pattern:
+- Business logic tangled with I/O → **FC/IS**: extract pure calculations into functional core; push all I/O to imperative shell
+- Read→compute→write in handlers → **Sandwich**: (1) impure read, (2) pure calculation, (3) impure write
+- Domain concepts as raw primitives → **Value Object**: self-validating, immutable, equality-by-value types
+- Void methods mutating in place → **Return-New-Instance** (Gilded Rose kata): return new instances instead of modifying
+- Deep nested immutable updates (3+ levels) → **Optics/Lenses**: composable getter/setter abstractions
+- `let`/`var` where `const` suffices → **Direct const migration**; loop-and-mutate → `map`/`filter`/`reduce`. Python: `Final` (PEP 591), `@dataclass(frozen=True)`
+- Internal state leaked via getters → **Defensive copy / unmodifiable wrapper**
+
+Native equivalents: Value Object → records (Java/C#/Kotlin); Return-New-Instance → `with` (C#), `copy()` (Kotlin), spread (JS/TS); Optics → FSharpPlus, monocle-ts, Higher-Kinded-J.
+
+Step 5 — Prioritize: Score = Concurrency Risk (Multi-threaded=3, Async=2, Single=1) × Testability Impact (I/O mocking=3, Setup ordering=2, Isolated=1) × Mutation Scope (Global=3, Cross-object=2, Object or Local=1). Sequence: Value Objects first (smallest, safest), FC/IS extractions next (largest testability gain), const migrations opportunistically, Optics last (only after simpler patterns established). Each step independently deployable.
+
+**OUTPUT**
+
+Summary table:
+| Location | Mutability Signal | Mutation Scope | Side Effect Type | Refactoring Pattern | Priority |
+
+If multiple signals share root cause, consolidate. Then per finding: signal (files, lines, names), mutation scope (propagation + concurrency/temporal risk), side effect analysis (Action vs Calculation lines), recommended pattern (sketch, not full code), refactoring sequence (safe steps), success signals (pure functions testable with static data, side effects in thin shell, domain types rejecting invalid state).
+
+Enforcement recommendations per language: JS/TS → ESLint (`functional/no-let`, `functional/immutable-data`, `ts-immutable/readonly-keyword`); Java → Mutability Detector, records; C#/.NET → Roslyn analyzers, `record` with `with`. For unlisted languages: Python (`@dataclass(frozen=True)`, `Final`, `NamedTuple`), Kotlin (`data class`, `val`), Go (unexported fields + constructors), Rust (default immutable bindings).
+
+Needs Human Review: list ambiguous cases — local mutation that's clearest algorithm expression, performance-critical hot paths, framework-mandated mutability (ORM entity hydration), state that appears shared but is thread-confined by framework guarantees, reactive/observable patterns where side effects are deferred to subscription (classify pipeline as Calculation, `subscribe()` as Action).
+
+If no signals found: "No pathological mutability found. Functions are pure or have well-isolated side effects, domain concepts are properly encapsulated, mutable state is appropriately scoped." Do not fabricate findings.
+
+Stop when all files analyzed. Do not modify anything.

package/pi-package/skills/narrative-article/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: narrative-article
+description: "Create engaging technical articles with narrative structure"
+metadata:
+  installed-from: "incitaciones"
+---
+# Write a Narrative-Driven Article
+
+We will collaborate to write a compelling article or blog post using the Three-Act narrative structure. We will work through four phases: Idea, Outline, Draft, and Review.
+
+## Phase 1: The Idea (The Setup)
+
+First, we must define the core of our story. Please answer these questions:
+
+1.  **What is the main topic or subject?**
+2.  **Who is the target audience?** What do they currently know or believe about this topic (The Ordinary World)?
+3.  **What is the central question or problem you want to address?** This is the "Inciting Incident" that will hook the reader. What puzzle will this article solve?
+4.  **What is the key takeaway or "new normal"?** What should the reader understand or be able to do after reading the article? This is the ultimate Resolution.
+
+Based on your answers, I will propose a title and a "hook" for the introduction.
+
+---
+
+## Phase 2: The Outline (The Three Acts)
+
+Once we agree on the core idea, I will create a detailed outline based on the Three-Act Structure:
+
+### Act I: The Setup
+-   **Hook:** Grab the reader's attention.
+-   **Introduce the Problem:** State the central question or conflict.
+-   **Establish the Stakes:** Explain why the reader should care.
+-   **Thesis Statement:** Promise the reader what they will learn.
+
+### Act II: The Exploration
+-   **Point 1 (Rising Action):** The first major argument or piece of evidence.
+-   **Point 2 (Obstacles):** Address counter-arguments, complexities, or common misconceptions.
+-   **Point 3 (The Midpoint):** A key turning point or "aha!" moment in the argument.
+-   **Point 4 (Escalation):** Deeper insights that build on the midpoint.
+
+### Act III: The Resolution
+-   **Climax (The Synthesis):** Present the main conclusion, tying all the points together.
+-   **Falling Action (Practical Application):** Provide concrete examples, practical steps, or implications.
+-   **The New Normal (The Call to Action):** State the key takeaway and what the reader should do or think now.
+
+We will review and refine this outline before moving on.
+
+---
+
+## Phase 3: The Draft (The Writing)
+
+With an approved outline, I will write the full draft of the article. I will focus on:
+-   Following the narrative flow of the outline.
+-   Maintaining a consistent tone and voice.
+-   Using clear and engaging language.
+
+---
+
+## Phase 4: The Review (The Refinement)
+
+Finally, I will perform an editorial review of the draft, checking for:
+-   **Clarity and Flow:** Is the article easy to read and understand?
+-   **Strength of Argument:** Is the narrative compelling and persuasive?
+-   **Grammar and Style:** Are there any grammatical errors or stylistic issues?
+-   **Impact:** Does the introduction hook the reader effectively? Does the conclusion provide a satisfying resolution?
+
+I will provide a list of suggested revisions for your approval.

package/pi-package/skills/optionality-review/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: optionality-review
+description: "Evaluate design decisions for flexibility and reversibility"
+metadata:
+  installed-from: "incitaciones"
+---
+# Optionality Review
+
+Review this [CODE/ARCHITECTURE/PLAN/DECISION] through the lens of strategic optionality.
+
+(See Quick Reference section below for optionality principles and red/green flags)
+
+## Work to Review
+
+[PASTE YOUR WORK OR SPECIFY FILE PATH]
+
+## Context (optional)
+
+[Any relevant context: timeline, constraints, uncertainty level]
+
+---
+
+## Phase 1: Decision Classification
+
+First, classify the key decisions using Bezos's framework:
+
+**Type 1 (One-Way Doors):** Consequential and irreversible
+- Require careful, methodical consideration
+- Need broad consultation
+- Examples: Core architecture, public APIs, major vendor commitments
+
+**Type 2 (Two-Way Doors):** Changeable and reversible
+- Should be made quickly with ~70% information
+- Can be changed if wrong
+- Examples: Internal tooling, feature flags, config choices
+
+For each major decision in this work:
+
+| Decision | Type | Reversibility | Decision Deadline | Justification |
+|----------|------|---------------|-------------------|---------------|
+| [What's being decided] | [1 or 2] | [EASY/MODERATE/HARD/IRREVERSIBLE] | [When must we decide?] | [Why this classification] |
+
+**Early Exit:** If NO Type 1 decisions identified, output abbreviated report:
+- List Type 2 decisions with brief notes
+- Recommend: "Proceed quickly - all decisions are reversible"
+- Skip Phases 2-6
+
+---
+
+## Phase 2: Alternative Paths
+
+For Type 1 decisions, evaluate the option space (2-4 alternatives):
+
+### Current Approach
+- Description: [Brief summary]
+- Locks in: [What future choices this constrains]
+- Enables: [What this makes possible]
+
+### Alternative A
+- Description: [Different approach]
+- Would preserve: [What options stay open]
+- Trade-off: [What we'd give up]
+
+### Alternative B (if applicable)
+- Description: [Another approach]
+- Would preserve: [What options stay open]
+- Trade-off: [What we'd give up]
+
+### Alternative C, D... (add more if needed for complex decisions)
+
+**Assessment:** Are alternatives adequately explored? [YES/NO]
+If NO, what should be investigated before committing?
+
+**For Type 2 decisions:** Don't deep-dive. Briefly note 1-2 alternatives, then move on - speed matters more than exhaustive analysis for reversible decisions.
+
+---
+
+## Phase 3: Exit Costs & Escape Hatches
+
+For Type 1 decisions from Phase 1, map the exit strategy:
+
+| Decision | Reversal Cost | Reversal Time | Escape Hatch |
+|----------|---------------|---------------|--------------|
+| [Choice made] | [LOW/MED/HIGH] | [hours/days/weeks/months] | [Concrete path to undo if needed] |
+| [Another choice] | [LOW/MED/HIGH] | [hours/days/weeks/months] | [How to exit] |
+
+**Red Flags:**
+- [ ] Irreversible decisions without clear justification
+- [ ] No escape hatches for major commitments
+- [ ] Assumptions treated as facts
+- [ ] "We can refactor later" without a concrete path
+
+**Reversibility Score:** [1-10] (10 = easily reversible)
+
+---
+
+## Phase 4: Failure Modes & Fallbacks
+
+What if things go wrong?
+
+| Failure Scenario | Probability | Impact | Fallback Plan | Recovery Cost |
+|------------------|-------------|--------|---------------|---------------|
+| [What could fail] | [L/M/H] | [L/M/H/CRITICAL] | [Plan B] | [time/effort] |
+
+**External Dependencies:**
+- [ ] Vendor lock-in: [None / Acceptable / Concerning]
+- [ ] Technology bets: [Reversible / Locked]
+- [ ] Regulatory assumptions: [Validated / Assumed]
+- [ ] Single points of failure identified: [YES/NO]
+
+**Resilience Score:** [1-10] (10 = multiple fallbacks, graceful degradation)
+
+**Convergence Check:** If Reversibility ≥7 AND Resilience ≥7, consider skipping to Final Report.
+
+---
+
+## Phase 5: Future Value Assessment
+
+Does this create or destroy options?
+
+### Options CREATED
+1. [New capability enabled]
+   - Enables: [What becomes possible]
+   - Value: [Why this matters]
+
+2. [Another capability]
+   - Enables: [What becomes possible]
+   - Value: [Why this matters]
+
+### Options DESTROYED (with justification)
+1. [Closed off possibility]
+   - Prevents: [What becomes harder/impossible]
+   - Justified because: [Why trade-off is acceptable]
+
+### Growth Potential
+- Can scale to 10x: [YES/PARTIALLY/NO]
+- Can add features without rewrite: [YES/PARTIALLY/NO]
+- Can be extracted/reused: [YES/PARTIALLY/NO]
+- Learning/telemetry built in: [YES/NO]
+
+**Future Value Score:** [1-10] (10 = maximum option creation)
+
+---
+
+## Phase 6: Decision Points & Triggers
+
+Where should we reassess?
+
+| Milestone | What to Assess | Reassess Trigger | Go/No-Go Criteria |
+|-----------|----------------|------------------|-------------------|
+| [When] | [What we're evaluating] | [What would cause review] | [How to decide] |
+| [Next milestone] | [Another assessment] | [Trigger condition] | [Decision criteria] |
+| [Future checkpoint] | [Long-term assessment] | [Warning sign] | [How to decide] |
+
+**Assumption Validation:**
+- [ ] Key assumptions explicitly stated
+- [ ] Validation checkpoints defined
+- [ ] Early warning metrics identified
+
+---
+
+## Final Report
+
+### Scores Summary
+- Reversibility: [X/10]
+- Resilience: [X/10]
+- Future Value: [X/10]
+- **Overall Optionality: [X/10]** (average, or lowest score if any ≤3)
+
+### Verdict
+
+**Optionality Assessment:** [FLEXIBLE | BALANCED | LOCKED_IN | CONCERNING]
+- FLEXIBLE (8-10): Excellent strategic flexibility
+- BALANCED (5-7): Acceptable trade-offs, some lock-in justified
+- LOCKED_IN (3-4): Significant constraints, ensure they're intentional
+- CONCERNING (1-2): High risk, reconsider approach
+
+**Key Findings:**
+1. [Most significant optionality issue or strength]
+2. [Second finding]
+3. [Third finding]
+
+### Recommendations
+
+**Before proceeding:**
+- [Critical actions to preserve flexibility]
+
+**Build in over time:**
+- [Strategic improvements for future flexibility]
+
+### The Bottom Line
+
+[2-3 sentences: Is the level of lock-in appropriate for our uncertainty level? Are we preserving the right options? What's the key trade-off?]
+
+**Human review recommended:** [YES/NO]
+**Reason:** [Why human judgment needed, or why assessment is sufficient]

package/pi-package/skills/parallel-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: parallel-review
+description: "High-stakes code review with parallel agent waves"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- skill: parallel-review, version: 1.2.0, status: verified -->
+# Parallel Review (Multi-Agent Code Review)
+
+Orchestrate a comprehensive, multi-agent code review using an extended parallel review workflow inspired by the Rule of 5 principle to achieve maximum defect detection (85-92%).
+
+## Role
+You are a Lead Orchestration Engineer. Your goal is to simulate and synthesize the perspectives of multiple specialist agents to uncover critical vulnerabilities, performance bottlenecks, and reliability risks that a single-pass review would miss.
+
+## Procedure
+
+1.  **Context Building:**
+    *   Identify the code to review.
+    *   Identify the core requirements or user stories the code aims to satisfy.
+    *   Read the code and any existing tests completely.
+
+2.  **Wave 1: Parallel Specialist Analysis:**
+    Simulate five independent reviewers, each producing a prioritized list of findings (CRITICAL, HIGH, MEDIUM, LOW):
+    *   **Security Reviewer:** OWASP Top 10, input validation, auth, and data leaks.
+    *   **Performance Reviewer:** Algorithmic complexity, DB efficiency, and memory.
+    *   **Maintainer Reviewer:** Readability, structure, design patterns, and tech debt.
+    *   **Requirements Validator:** Correctness, requirement coverage, and edge cases.
+    *   **Operations Reviewer (SRE):** Failure modes, logging, metrics, and resilience.
+
+3.  **Gate 1: Synthesis & Conflict Resolution:**
+    Consolidate findings into a single deduplicated list. Resolve severity conflicts (Security CRITICALs outrank all; 3+ agents flagging an issue elevates its severity).
+
+4.  **Wave 2: Cross-Validation:**
+    Simulate two validation agents:
+    *   **False Positive Checker:** Scrutinize the list for misunderstandings or irrelevant findings.
+    *   **Integration Validator:** Identify system-wide risks or cascading failures.
+
+5.  **Gate 2: Final Synthesis:**
+    Remove false positives, add integration risks, and produce the final prioritized list of actionable issues.
+
+6.  **Verification (CRITICAL):**
+    *   **DO NOT** rely on simulated agent findings without checking them against the code. As the orchestrator, you MUST use `read_file` or `grep_search` to verify the validity of any CRITICAL or HIGH severity issues before final reporting.
+    *   Verify that suggested fixes (e.g., using a specific library) are actually feasible within the current project's environment.
+
+7.  **Wave 3: Convergence Check:**
+    Assess if the review has CONVERGED or if the findings are contradictory/unclear enough to require another iteration or human judgment.
+
+## Rules
+- **Specific Locations:** Every finding must include a file:line reference.
+- **Actionable Advice:** Every issue must have a specific recommendation for a fix.
+- **Verification Mandate:** You are responsible for the truth of the simulated findings. Verify high-severity claims manually.
+
+## References
+- **Templates:** Use `references/templates.md` for wave outputs and the final report.
+- **Criteria:** See `references/criteria.md` for severity definitions and convergence rules.

package/pi-package/skills/parallel-review/references/criteria.md

@@ -0,0 +1,34 @@
+# Multi-Agent Code Review Criteria
+
+Use these criteria to categorize findings and determine when the review process is complete.
+
+## Issue Severity Definitions
+
+| Severity | Criteria | Example Findings |
+| :--- | :--- | :--- |
+| **CRITICAL** | Severe security vulnerability, data loss risk, or fundamental logic failure that makes the code unshipable. | SQL Injection, plaintext passwords, unhandled exceptions in core path. |
+| **HIGH** | Significant performance issue, major regression risk, or violation of key requirements. | Missing index on hot query, non-singular requirement, missing error states. |
+| **MEDIUM** | Minor technical debt, sub-optimal pattern, or readability issues. | Magic strings, DRY violations, lack of docstrings, magic numbers. |
+| **LOW** | Nice to have. Stylistic improvements, minor metadata gaps, or typos in non-critical comments. | Minor formatting, redundant comments, small consistency improvements. |
+
+## Convergence Criteria
+
+**CONVERGED** if:
+- All CRITICAL and HIGH severity issues have been cross-validated by at least two agents (e.g., Security Reviewer and False Positive Checker).
+- Gate 1 and Gate 2 synthesis steps result in a stable list of issues with no major contradictions.
+- The Integration Validator confirms that no new cascading failures are likely.
+
+**ITERATE** if:
+- Wave 2 identifies more than two HIGH or one CRITICAL severity issue that were missed in Wave 1.
+- Specialist agents have directly contradictory findings on a CRITICAL issue.
+
+**NEEDS_HUMAN** if:
+- After two full multi-agent cycles, no consensus is reached on a CRITICAL issue.
+- The specialist agents identify a foundational architectural conflict.
+
+## Verification Checklist (For Orchestrator)
+
+As the Lead Orchestration Engineer, you MUST:
+- [ ] Use `read_file` to confirm that every CRITICAL finding actually exists at the cited file:line.
+- [ ] Cross-check the "Requirements Validator" findings against the actual specification file (if provided).
+- [ ] Verify that suggested performance optimizations don't violate existing project constraints (e.g., using a library that is explicitly forbidden).

package/pi-package/skills/parallel-review/references/templates.md

@@ -0,0 +1,59 @@
+# Multi-Agent Code Review Templates
+
+Use these templates to structure the waves and final reporting of the multi-agent code review.
+
+## Wave 1 Output Template
+
+```markdown
+### WAVE 1: Parallel Analysis Findings
+
+#### 1. Security Reviewer
+- [Severity] [Description] - [File:Line]
+- [Severity] ...
+
+#### 2. Performance Reviewer
+- [Severity] [Description] - [File:Line]
+
+... [Remaining Reviewers]
+```
+
+## Wave 2 & 3 Convergence Check Template
+
+```markdown
+### WAVE 3: Convergence Check
+
+**Status:** [CONVERGED | ITERATE | NEEDS_HUMAN]
+**Confidence Score:** [0-100%]
+**Rationale:** [1-2 sentences explaining why the review is complete or requires more focus]
+```
+
+## Final Report Template
+
+```markdown
+# Multi-Agent Code Review Final Report
+
+**Code:** [Short description/path] | **Convergence:** Wave [N]
+
+## Synthesized Issue Summary
+| Severity | Count | Primary Focus |
+| :--- | :--- | :--- |
+| **CRITICAL** | [count] | Security / Logic Failures |
+| **HIGH** | [count] | Performance / Reliability |
+| **MEDIUM** | [count] | Maintainability / Tech Debt |
+| **LOW** | [count] | Clarity / Style |
+
+## Top 3 Critical Findings (Verified)
+1. **[ID] [Description]** - [File:Line]
+   *   **Impact:** [Why this blocks implementation or causes failure]
+   *   **Fix:** [Specific actionable step]
+
+2. **[ID] ...**
+
+## Final Actionable List
+1. [Verified Action 1 - specific and actionable]
+2. [Verified Action 2 - specific and actionable]
+3. [Verified Action 3 - specific and actionable]
+
+## Verdict: [READY_TO_MERGE | NEEDS_FIXES | BLOCKS_MERGE]
+**Rationale:** [Final summary of system-wide health and prioritized fixes]
+```