@caoscompanybr/merlin 3.5.0

package/.merlin-core/commands/planning/create-plan.md

@@ -0,0 +1,184 @@
+---
+description: Create detailed implementation plans through interactive research and iteration
+model: opus
+---
+
+# Create Implementation Plan
+
+You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.
+
+## Initial Response
+
+When this command is invoked:
+
+1. **If parameters were provided** (file path or ticket reference):
+   - Skip the default message
+   - Read all provided files FULLY
+   - Begin the research process
+
+2. **If no parameters provided**, respond with:
+
+```
+I'll help you create a detailed implementation plan. Let me start by understanding what we're building.
+
+Please provide:
+1. The task/ticket description (or reference to a ticket file)
+2. Any relevant context, constraints, or specific requirements
+3. Links to related research or previous implementations
+
+Tip: You can invoke with a file directly: /plan thoughts/shared/research/my-research.md
+```
+
+Then wait for user input.
+
+## Process Steps
+
+### Step 1: Context Gathering & Initial Analysis
+
+1. **Read all mentioned files FULLY** (no limit/offset)
+2. **Spawn research agents in parallel:**
+   - Use **scout** to find all files related to the task
+   - Use **researcher** to understand current implementation
+   - Check `thoughts/shared/` for existing documents on this topic
+3. **Read all files identified by research agents**
+4. **Analyze and verify understanding:**
+   - Cross-reference requirements with actual code
+   - Identify discrepancies or misunderstandings
+   - Note assumptions needing verification
+
+5. **Present informed understanding:**
+
+```
+Based on the ticket and my research, I understand we need to [summary].
+
+I've found that:
+- [Current implementation detail with file:line reference]
+- [Relevant pattern or constraint discovered]
+
+Questions before I draft the plan:
+1. [Specific, informed question]
+2. [Question about scope or approach]
+```
+
+### Step 2: Draft the Plan
+
+After gathering context, create a plan with this structure:
+
+```markdown
+---
+date: [ISO 8601]
+architect: Aria
+ticket: [reference if provided]
+status: draft
+complexity: [simple|standard|complex]
+---
+
+# Implementation Plan: [Title]
+
+## Overview
+
+[2-3 sentence summary of what we're building and why]
+
+## Affected Files
+
+| File            | Change Type | Description     |
+| --------------- | ----------- | --------------- |
+| path/to/file.ts | modify      | What changes    |
+| path/to/new.ts  | create      | Why it's needed |
+
+## Phase 1: [Phase Name]
+
+### Changes
+
+1. [Specific change with file:line reference]
+2. [Specific change]
+
+### Success Criteria
+
+**Automated Verification:**
+
+- [ ] `npm test` passes
+- [ ] `npm run lint` passes
+
+**Manual Verification:**
+
+- [ ] [Human testing step with expected outcome]
+
+## Phase 2: [Phase Name]
+
+[Same structure]
+
+## Risks & Mitigations
+
+- Risk: [description] → Mitigation: [approach]
+
+## Out of Scope
+
+- [What this plan explicitly does NOT cover]
+```
+
+### Step 2.5: Reflect Before Presenting
+
+Before presenting the plan to the user, pause for a **STANDARD reflection**:
+
+> **GOAL CHECK:** Does this plan solve the stated problem? Am I building what was requested?
+> **EVIDENCE CHECK:** Does every phase trace to a requirement or codebase reality? Am I inventing features not in the spec (Article IV)?
+> **UNCERTAINTY CHECK:** Are the success criteria actually testable? What assumptions am I making about the codebase that I haven't verified?
+> **NEXT STEP CHECK:** Is this plan ready to present, or should I research one more area first?
+
+If the reflection reveals invented requirements or untestable criteria, revise the plan before presenting.
+
+### Step 3: Review & Iterate
+
+- Present the draft plan to the user
+- Address feedback and questions
+- Iterate until the user approves
+- Each iteration should improve specificity
+
+### Step 4: Save the Plan
+
+Save the approved plan to `thoughts/shared/plans/` with naming:
+`YYYY-MM-DD-[ticket-or-description].md`
+
+Confirm save location to the user:
+
+```
+Plan saved to: thoughts/shared/plans/[filename].md
+
+To implement: /implement thoughts/shared/plans/[filename].md
+To iterate: /iterate-plan thoughts/shared/plans/[filename].md
+```
+
+After saving, **rebuild the thoughts index**:
+
+```bash
+node .merlin-core/tools/merlin-tools.js index
+```
+
+## Spec Review Loop (Post-Save)
+
+After saving the plan, run a quick spec completeness check by dispatching a subagent:
+
+1. **Dispatch reviewer** — Spawn a general-purpose subagent to review the saved plan file for:
+   - TODO markers, placeholder text, or "TBD" sections
+   - Incomplete sections or noticeably less-detailed areas
+   - Internal contradictions or conflicting requirements
+   - Scope creep — unrequested features or over-engineering (Article IV)
+   - Untestable success criteria
+
+2. **If issues found** — Fix them in the plan file and re-dispatch the reviewer. Maximum 3 iterations.
+
+3. **If clean** — Present the plan to the user for final review before implementation.
+
+This loop catches spec gaps before implementation begins — the cheapest time to fix them.
+
+## Quality Checklist
+
+Before presenting any plan, verify:
+
+- [ ] Every change references specific files and locations
+- [ ] Success criteria split into Automated and Manual
+- [ ] Phases are ordered by dependency (earlier phases don't depend on later)
+- [ ] No invented requirements (all trace to user input or codebase reality)
+- [ ] Risks and mitigations are realistic
+- [ ] Out of scope is explicitly stated

package/.merlin-core/commands/planning/iterate-plan.md

@@ -0,0 +1,45 @@
+---
+description: Update an existing plan with new information or feedback
+model: opus
+---
+
+# Iterate Plan
+
+Update an existing implementation plan based on new information, feedback, or changed requirements.
+
+## Process
+
+1. **Read the existing plan FULLY**
+2. **Read any new context provided** (feedback, new requirements, research)
+3. **Identify what needs to change:**
+   - New phases needed?
+   - Existing phases need modification?
+   - Success criteria need updating?
+   - Scope changed?
+
+4. **Present diff-style summary:**
+
+```
+Plan Update: [plan name]
+
+Changes:
+- Phase 2: [what changed and why]
+- New Phase 4: [added because...]
+- Removed: [what was removed and why]
+
+Updated plan saved to: [same path, overwritten]
+```
+
+5. **Update the plan file** with changes tracked via date in frontmatter
+
+6. **Rebuild the thoughts index** after updating:
+   ```bash
+   node .merlin-core/tools/merlin-tools.js index
+   ```
+
+## Rules
+
+- Preserve completed phases (don't modify checked items)
+- Explain WHY each change is needed
+- Keep the plan's overall structure intact
+- If scope increased significantly, recommend splitting into multiple plans

package/.merlin-core/commands/planning/validate-plan.md

@@ -0,0 +1,48 @@
+---
+description: Verify implementation correctness against the plan
+model: opus
+---
+
+# Validate Plan
+
+Verify that an implementation matches its plan. Run after /implement to confirm everything was built correctly.
+
+## Process
+
+1. **Read the plan FULLY**
+2. **For each phase, verify:**
+   - All changes listed were actually made
+   - Code matches the plan's intent
+   - No unplanned changes were introduced (Principle IV: No Invention)
+
+3. **Run all success criteria:**
+   - Execute every automated verification command
+   - List manual verification steps for user
+
+3.5. **Verify must_haves (if present):**
+
+- Extract the `## Must-Haves` section from the plan
+- For each truth: verify the invariant holds (run command or present manual step)
+- For each artifact: verify the file/pattern exists
+- For each key_link: verify traceability (implementation_ref exists)
+- Include must_haves results in the validation report
+- If no must_haves section exists, skip this step
+
+4. **Present validation report:**
+
+```
+Plan Validation: [plan name]
+
+Phase 1: [PASS/FAIL]
+- [x] Change 1 verified
+- [ ] Change 2 missing: [details]
+
+Phase 2: [PASS/FAIL]
+- [x] All changes verified
+
+Automated Tests: [PASS/FAIL]
+Manual Verification Needed:
+- [ ] [Step for user to verify]
+
+Overall: [COMPLETE / INCOMPLETE]
+```

package/.merlin-core/commands/research/analyze-issue.md

@@ -0,0 +1,155 @@
+---
+description: Convert a GitHub issue or ticket description into a structured spec ready for /plan
+model: opus
+version: "3.0.0"
+---
+
+# /analyze-issue — Issue to Spec Bridge
+
+Converts a raw GitHub issue (or any ticket text) into a structured implementation
+specification that feeds directly into `/plan`. Bridges the gap between
+issue tracker and the Folloni Funnel.
+
+## Usage
+
+```
+/analyze-issue #42                    → Fetch and analyze GitHub issue #42 via gh CLI
+/analyze-issue [paste issue text]     → Analyze pasted issue/ticket text directly
+/analyze-issue --save                 → Save output to thoughts/shared/research/ automatically
+```
+
+## Protocol
+
+### Step 1: Acquire the Issue
+
+**If issue number provided (#N):**
+
+```bash
+gh issue view N --json title,body,labels,comments,assignees
+```
+
+If `gh` is not available or not authenticated, ask the user to paste the issue text.
+
+**If text pasted:**
+Use the pasted content directly.
+
+### Step 2: Extract Structure
+
+Parse the issue into these components:
+
+**Requirements (MoSCoW classification):**
+
+- **Must Have** — explicit requirements, acceptance criteria, non-negotiable constraints
+- **Should Have** — implied expectations, "it would be nice if", best practices
+- **Could Have** — mentioned possibilities, stretch goals
+- **Won't Have** — explicitly out of scope, deferred items, "not this ticket"
+
+If the issue doesn't use MoSCoW language, infer the classification from the language used
+("must", "should", "can", "not in scope", "later", "v2", etc.)
+
+**Acceptance Criteria:**
+
+- Extract explicit criteria if present
+- Infer from the issue description if not explicit
+- Frame as testable conditions: "Given X, when Y, then Z"
+
+**Constraints:**
+
+- Technical constraints mentioned (API version, library choice, backwards compatibility)
+- Performance constraints (response time, load)
+- Security constraints (auth required, no PII, etc.)
+
+**Affected Areas (via Scout):**
+Spawn Scout to identify likely affected files based on the issue description.
+Look for: mentioned file names, component names, API endpoints, database tables.
+
+### Step 3: Classify Complexity and Risk
+
+**Complexity:**
+| Level | Signals |
+|-------|---------|
+| Simple | Single file change, clear solution, no external dependencies |
+| Standard | Multiple files, some design decisions, 1-2 external dependencies |
+| Complex | Architecture decisions, many files, new external dependencies, data migration |
+
+**Risk:**
+| Level | Signals |
+|-------|---------|
+| Low | Isolated change, well-tested area, no production data affected |
+| Medium | Shared code, user-facing change, external API affected |
+| High | Authentication, payments, data migration, breaking API changes |
+
+### Step 4: Output Spec
+
+Produce a spec document in this format:
+
+```markdown
+# Issue Spec: [Issue Title]
+
+**Source:** #[N] / [link if available]
+**Complexity:** [simple|standard|complex]
+**Risk:** [low|medium|high]
+**Estimated Phases:** [N]
+
+## Problem Statement
+
+[1-2 sentences: what problem does this issue solve?]
+
+## Requirements
+
+### Must Have
+
+- [ ] [testable requirement]
+- [ ] [testable requirement]
+
+### Should Have
+
+- [ ] [testable requirement]
+
+### Won't Have (This Ticket)
+
+- [explicitly out of scope]
+
+## Acceptance Criteria
+
+- Given [context], when [action], then [outcome]
+- Given [context], when [action], then [outcome]
+
+## Likely Affected Areas
+
+- [file or module] — [reason]
+- [file or module] — [reason]
+
+## Constraints
+
+- [technical constraint]
+- [security constraint]
+
+## Open Questions
+
+- [unclear requirement that needs clarification before planning]
+```
+
+### Step 5: Save (if --save or user confirms)
+
+Save to: `thoughts/shared/research/YYYY-MM-DD-issue-[N or slug].md`
+
+After saving, rebuild the thoughts index:
+
+```bash
+node .merlin-core/tools/merlin-tools.js index
+```
+
+Then prompt:
+
+```
+Spec saved. Ready to create plan?
+→ /plan thoughts/shared/research/[filename].md
+```
+
+## Integration
+
+- Output feeds directly into [/plan](../planning/create-plan.md)
+- Uses [elicitation](../../skills/general/elicitation/SKILL.md) — MoSCoW and Impact Mapping techniques
+- Spawns Scout agent for affected area detection
+- Saves to [thoughts/shared/research/](../../thoughts/shared/research/) for persistence

package/.merlin-core/commands/research/research-codebase.md

@@ -0,0 +1,157 @@
+---
+description: Comprehensive codebase research through parallel sub-agents with knowledge persistence
+model: opus
+---
+
+# Research Codebase
+
+You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
+
+## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
+
+- DO NOT suggest improvements or changes unless the user explicitly asks
+- DO NOT perform root cause analysis unless explicitly asked
+- DO NOT propose future enhancements unless explicitly asked
+- DO NOT critique the implementation or identify problems
+- ONLY describe what exists, where it exists, how it works, and how components interact
+- You are creating a technical map/documentation of the existing system
+
+## Identity Gate — when researching a PERSON, COMPANY, or BRAND (external)
+
+This command defaults to CODEBASE research. When the target is instead an **external person, company, or brand**, a wrong identity is the #1 failure mode — and it wastes the user's time AND paid API calls (Apify). Pass this gate BEFORE spawning research agents or scraping anything:
+
+1. **Exact source?** Do you have the specific profile URL/handle/site for the target — not just a name? If you only have a name, **STOP and ask the user for the exact profile(s)**. Never name-search and assume.
+2. **Homonym risk?** Common name, or a search shows multiple candidates? **Ask the user to confirm the exact handle/URL** before any deep research.
+3. **Walled gardens** (Instagram, LinkedIn, X, Facebook, TikTok) cannot be read by WebFetch — use the **`apify-scrape` skill** (Iris has `Bash` + Apify). The FIRST scrape is the cheapest identity check: confirm the **bio link / current company / name** match the expected person BEFORE deeper passes.
+4. **Tag everything** VERIFIED / INFERENCE / NAME-MATCH. A search hit on a matching name is NAME-MATCH, not confirmed identity. Run `development/checklists/source-verification-checklist.md` before finalizing.
+
+> Why this gate exists: a non-technical Merlin user cannot tell a confident-but-wrong dossier from a correct one. Confirming the source costs one question; the wrong path costs API credits, time, and trust. (Lesson from a real identity-research incident — three homonyms were conflated because the provided profiles were never actually read.)
+
+## Initial Response
+
+When this command is invoked, respond with:
+
+```
+I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
+```
+
+Then wait for the user's research query.
+
+## Process Steps
+
+### Step 1: Read Mentioned Files
+
+- If the user mentions specific files, read them FULLY first
+- Use the Read tool WITHOUT limit/offset parameters
+- Read these files yourself in the main context before spawning sub-tasks
+
+### Step 2: Decompose the Research Question
+
+- Break down the query into composable research areas
+- Identify specific components, patterns, or concepts to investigate
+- Create a research plan using TodoWrite to track subtasks
+- Consider which directories, files, or patterns are relevant
+
+### Step 3: Spawn Parallel Research Agents
+
+Use Merlin's specialized agents concurrently:
+
+**For codebase research:**
+
+- Use the **scout** agent to find WHERE files and components live
+- Use the **researcher** agent to understand HOW specific code works
+- Use the **scout** agent again to find examples of existing patterns
+
+**For knowledge base:**
+
+- Check `thoughts/shared/research/` for existing research on this topic
+- Check `thoughts/shared/decisions/` for relevant ADRs
+
+**For web research (only if explicitly requested):**
+
+- Use the **web-researcher** agent (Iris) for external documentation
+- For a PERSON/COMPANY/BRAND target: pass the **Identity Gate** above first; scrape walled-garden profiles via the **`apify-scrape`** skill, not WebFetch
+- Tag findings VERIFIED / INFERENCE / NAME-MATCH; include links + retrieval dates in final report
+
+**Key principles:**
+
+- Start with Scout to find what exists
+- Then use Researcher on the most promising findings
+- Run multiple agents in parallel for different search areas
+- Agents are documentarians, not critics
+
+### Step 4: Synthesize Findings
+
+- Wait for ALL sub-agents to complete
+- Compile results with codebase findings as primary source of truth
+- Connect findings across different components
+- Include specific file paths and line numbers
+
+### Step 4.5: Reflect Before Documenting
+
+Before writing the research document, pause for a **STANDARD reflection**:
+
+> **GOAL CHECK:** Am I answering the original research question? Has the scope drifted?
+> **EVIDENCE CHECK:** Are my findings complete? Am I missing a critical area? Do any findings contradict each other?
+> **UNCERTAINTY CHECK:** What assumptions am I making about how components connect? What would I need to verify?
+> **NEXT STEP CHECK:** Should I document now, or do I need one more research pass on a gap I identified?
+
+If the reflection reveals gaps, spawn additional research agents before proceeding to Step 5.
+
+### Step 5: Output Research Document
+
+Save findings to `thoughts/shared/research/` using this format:
+
+```markdown
+---
+date: [ISO 8601]
+researcher: Sage
+topic: "[Research Question]"
+tags: [relevant, tags]
+status: complete
+---
+
+# Research: [Title]
+
+## Research Question
+
+[Original query]
+
+## Summary
+
+[Key findings in 3-5 bullet points]
+
+## Detailed Findings
+
+### [Component/Area 1]
+
+[Findings with file:line references]
+
+### [Component/Area 2]
+
+[Findings with file:line references]
+
+## Architecture Map
+
+[How components connect]
+
+## Key Files
+
+| File      | Purpose     |
+| --------- | ----------- |
+| path:line | description |
+```
+
+### Step 6: Rebuild Thoughts Index
+
+After saving, rebuild the index so the research is immediately discoverable:
+
+```bash
+node .merlin-core/tools/merlin-tools.js index
+```
+
+### Step 7: Present to User
+
+- Show a concise summary with the most important findings
+- Reference the saved document for full details
+- Ask if any areas need deeper exploration

package/.merlin-core/commands/review/adversarial-review.md

@@ -0,0 +1,112 @@
+---
+description: Execute adversarial review to actively find problems in implementation before approval
+model: opus
+---
+
+# Adversarial Review
+
+Execute an adversarial review of the current implementation. Your goal is to **find problems**, not verify correctness. Activate your inner hacker, skeptic, and critic.
+
+## Usage
+
+```
+/adversarial-review [plan-file-path]
+```
+
+If no path provided, locate the most recent plan in `thoughts/shared/plans/`.
+
+## Process Steps
+
+### Step 1: Load Context
+
+1. Read the plan file fully — understand what SHOULD have been built
+2. Run `git diff main...HEAD --stat` to see what WAS changed
+3. Run `git diff main...HEAD` to see the actual code changes
+
+### Step 2: Git-Reality Cross-Reference
+
+For each item in the plan:
+
+- Find the corresponding code change in the git diff
+- If no corresponding change: flag as **MISSING IMPLEMENTATION**
+
+For each file in the git diff:
+
+- Find the corresponding plan item
+- If no plan item: flag as **ORPHAN CHANGE (Article IV violation)**
+
+Report:
+
+```
+Plan items: [N] | Code changes: [M] | Orphans: [X] | Missing: [Y]
+```
+
+### Step 3: Deep File Review
+
+For each changed file:
+
+1. Read the FULL file (not just the diff)
+2. Read the diff to understand what changed
+3. Execute all 7 axes of the attack surface analysis:
+   - **Security:** injection, auth, data exposure, secrets
+   - **Logic:** off-by-one, race conditions, null checks, error handling
+   - **Edge Cases:** empty inputs, max values, unicode, timeouts
+   - **Spec Deviation:** does the code match the plan's intent?
+   - **Untested Paths:** code without test coverage
+   - **Performance:** N+1, unbounded loops, memory leaks
+   - **Scale:** bottlenecks at 10x/100x, unbounded growth, pool exhaustion
+
+### Step 4: Run Adversarial Checklist
+
+Use the adversarial review checklist from `.merlin-core/development/checklists/adversarial-review-checklist.md` as a systematic guide.
+
+### Step 5: DEEP Reflection
+
+Before issuing your verdict, perform a **DEEP reflection**:
+
+> **GOAL CHECK:** Am I finding real problems, or nitpicking? Have I been thorough across all 7 axes?
+> **EVIDENCE CHECK:** Are my findings backed by specific code references? Could I explain each finding to the developer?
+> **UNCERTAINTY CHECK:** Am I confident in the severity ratings? Could any HIGH be MEDIUM, or vice versa?
+> **COUNTER-ARGUMENT:** What would the developer say to defend each finding? Is the defense valid?
+
+### Step 6: Present Findings
+
+```markdown
+## Adversarial Review: [Feature/Module]
+
+Date: [date]
+Reviewer: Quinn (Adversarial Mode)
+Plan: [plan reference]
+Verdict: [CLEAR | CONDITIONAL | BLOCKED]
+
+### Git-Reality Cross-Reference
+
+- Plan items: [N] | Code changes: [M] | Orphans: [X] | Missing: [Y]
+
+### Findings
+
+1. [CRITICAL] [Axis] Description — file:line
+   Evidence: [specific code reference]
+   Fix: [suggested remediation]
+
+2. [HIGH] [Axis] Description — file:line
+   Evidence: [specific code reference]
+   Fix: [suggested remediation]
+
+### Summary
+
+[1-2 sentence overall assessment]
+```
+
+### Step 7: Offer to Fix
+
+If verdict is CONDITIONAL:
+
+- Offer to fix the high-severity issues immediately
+- After fixing, re-run the adversarial review on the fixed code
+
+## Constitution Compliance
+
+- **Article IV (No Invention):** Git-reality cross-reference enforces traceability
+- **Article V (Quality First):** Adversarial review is a quality gate
+- **Article VII (Human Gates):** Final verdict requires human acknowledgment