@caoscompanybr/merlin 3.5.0

package/.merlin-core/commands/README.md

@@ -0,0 +1,19 @@
+# Slash Commands
+
+The commands module provides a comprehensive set of slash commands organized by functional category. Commands span research and analysis, planning and design, implementation and execution, git operations, session management, and code review workflows.
+
+## Contents
+
+- **research/** - Commands for information gathering, analysis, and exploration (`/research`, `/analyze-issue`)
+- **planning/** - Commands for design, planning, and architecture decisions
+- **implementation/** - Commands for coding, testing, and deployment (`/implement`, `/oneshot`, `/tdd`)
+- **git/** - Commands for version control workflows and operations
+- **session/** - Commands for session management and context switching (`/fast-start`, `/handoff`, `/resume-handoff`, `/check-objectives`, `/conclude`)
+- **review/** - Commands for code review and quality assessment (`/review`, `/debug`, `/doubts`, `/check`)
+- **special/** - Meta and alignment commands (`/elicit`, `/common-ground`, `/skill-audit`)
+
+## Related
+
+- [Skills](../skills/README.md)
+- [Development](../development/README.md)
+- [Schemas](../schemas/README.md)

package/.merlin-core/commands/founder-mode.md

@@ -0,0 +1,51 @@
+---
+description: Override agent authority for rapid prototyping
+model: opus
+---
+
+# Founder Mode
+
+Temporarily override Agent Authority (Constitution Article II) for rapid prototyping by a single operator.
+
+## When to Use
+
+- Solo founder building an MVP
+- Emergency hotfixes where delegation overhead is unacceptable
+- Rapid prototyping sessions where switching agents would slow you down
+
+## What Changes
+
+In Founder Mode:
+
+- **Article II (Agent Authority)** is RELAXED: you may perform tasks normally reserved for specialized agents
+- **Article III (Spec-Driven Development)** is RELAXED: you may code without a full plan for small changes
+- **All other Constitution articles remain enforced**, especially:
+  - Article V (Quality First): tests and quality gates still apply
+  - Article VII (Human Gates): HIGH-stake actions still require approval
+
+## Activation
+
+When the user invokes `/founder-mode`, respond:
+
+```
+Founder Mode: ACTIVE
+Duration: This session only
+
+Relaxed:
+- Agent Authority (Article II) - you may act across agent boundaries
+- Spec-Driven Development (Article III) - plan-optional for <3 file changes
+
+Still Enforced:
+- Quality First (Article V)
+- Human Gates (Article VII)
+- No Invention (Article IV)
+
+Type /founder-mode off to deactivate.
+```
+
+## Rules
+
+- Founder Mode is session-scoped only. It does NOT persist across sessions.
+- Log all actions taken under Founder Mode to `.merlin/founder-mode-log.md`
+- If a change touches more than 5 files, recommend creating a plan anyway
+- Never auto-activate. Only activate on explicit `/founder-mode` command.

package/.merlin-core/commands/git/commit.md

@@ -0,0 +1,35 @@
+---
+description: Create well-structured git commits with mandatory pre-flight secret scan. Alias to /safe-commit (kept for backwards compatibility).
+model: sonnet
+---
+
+# Commit (alias of /safe-commit)
+
+> **Note:** As of 2026-04-27, every commit in Merlin projects passes through
+> gitleaks pre-flight automatically. The `/commit` command is an alias for
+> `/safe-commit`. The behavior is the same — both invoke the safe path with
+> mandatory secret scanning before any commit is written.
+>
+> See [`safe-commit`](./safe-commit.md) for the full process.
+>
+> **TL;DR:**
+>
+> 1. Step 0 — `gitleaks protect --source . --staged` (abort on finding)
+> 2. Step 1 — Read `operations.git` config
+> 3. Step 2 — `git status` + `git diff --staged`
+> 4. Step 3 — Draft message (conventional / jira / plain)
+> 5. Step 4 — Present + commit
+>
+> Use `--skip-secret-scan` ONLY for legitimate edge cases (test fixtures, docs,
+> migration cleanup, false positives) and ALWAYS provide a `secret-scan-skip:`
+> reason in the commit body.
+>
+> If gitleaks is not installed in the project, the **`secret-safe-commit`**
+> skill provides a one-command bootstrap. Reactive runbook for already-leaked
+> secrets: **`purge-leaked-secret`** skill.
+
+---
+
+For new commits, prefer invoking `/safe-commit` directly. This file exists so
+that historic muscle memory and existing tooling that calls `/commit` continue
+to work — but the behavior is now identical to `/safe-commit`.

package/.merlin-core/commands/git/describe-pr.md

@@ -0,0 +1,43 @@
+---
+description: Generate comprehensive PR descriptions from branch changes
+model: sonnet
+---
+
+# Describe PR
+
+Generate a comprehensive pull request description from the current branch's changes.
+
+## Process
+
+1. Determine base branch (main/master/develop)
+2. Run `git log [base]..HEAD` to see all commits
+3. Run `git diff [base]...HEAD` to see all changes
+4. Analyze the full scope of changes
+
+## Output Format
+
+```markdown
+## Summary
+
+[1-3 bullet points describing the changes]
+
+## Changes
+
+- [File-level changes grouped by category]
+
+## Testing
+
+- [ ] Automated tests pass
+- [ ] [Manual verification steps]
+
+## Screenshots
+
+[If UI changes, note where screenshots should go]
+```
+
+## Rules
+
+- Include ALL commits, not just the latest
+- Group changes logically, not by file
+- Mention breaking changes prominently
+- Link to relevant tickets/stories if identifiable

package/.merlin-core/commands/git/safe-commit.md

@@ -0,0 +1,182 @@
+---
+description: Create well-structured git commits with mandatory pre-flight secret scan (gitleaks). Aliased as /commit.
+model: sonnet
+aliases: [commit]
+---
+
+# Safe Commit
+
+Create a git commit AFTER running gitleaks on the staged diff. **Never commits
+secrets to history.** Replaces the old plain `/commit` command — every commit
+in Merlin projects now goes through this safe path.
+
+## Process (executed in order — abort on any failure)
+
+### Step 0 — Pre-flight secret scan (gitleaks)
+
+This step runs FIRST, before any analysis or message drafting. The skill
+`secret-safe-commit` provides the canonical implementation.
+
+```bash
+# If gitleaks is not installed, install it first via the skill bootstrap:
+#   pip install pre-commit && pre-commit install
+#   (this also installs .pre-commit-config.yaml + .gitleaks.toml templates)
+
+# Scan staged changes only (fast, < 2s for typical diffs):
+gitleaks protect --source . --staged --redact --verbose
+```
+
+**On finding(s) detected:**
+
+1. **ABORT immediately** — do NOT proceed to draft a commit message
+2. Show the user the exact rule + path + line where the leak was detected
+3. Recommend invoking the **`purge-leaked-secret`** skill (the leaked credential
+   is now in your working tree, possibly already in history if a previous
+   `/commit --skip-secret-scan` was used)
+4. Concrete next actions: `git restore --staged <file>` to unstage + rotate
+   credential at the upstream provider + add the file to `.gitignore`
+
+**On clean scan:** continue to Step 1.
+
+### Step 1 — Read operations config
+
+Check `.merlin-core/project-config.yaml → operations.git`:
+
+- `commit_convention` → conventional, jira, plain, custom
+- `commit_prefix` → prepended to messages (e.g., Jira ticket)
+- Missing config → default to conventional commits
+
+### Step 2 — Inspect staged changes
+
+```bash
+git status
+git diff --staged
+```
+
+If nothing is staged, suggest files to stage based on recent changes. **Never
+auto-stage with `git add -A`** — risk of including secrets, large binaries, or
+unrelated changes.
+
+### Step 3 — Analyze and draft
+
+Determine:
+
+- **Type:** feat, fix, refactor, docs, test, chore, perf, ci, style, build, security
+- **Scope:** affected component or area
+- **Description:** concise summary of WHY (not what)
+
+Draft message in the configured format (see Formats below).
+
+### Step 4 — Present + commit
+
+Show the drafted message to the user. On approval:
+
+```bash
+git commit -m "<message>"
+```
+
+Pre-commit hooks (if configured via `operations.git.pre_commit_hooks`) run
+automatically — **do not bypass with `--no-verify`**. The gitleaks step in
+Step 0 is independent of any project-level pre-commit hooks (defense in depth).
+
+---
+
+## The `--skip-secret-scan` flag (LAST RESORT — use rarely)
+
+There are exactly 4 legitimate reasons to bypass the gitleaks pre-flight:
+
+1. **Test fixtures with intentionally fake secrets** (test data with `EXAMPLE_KEY=` style values that match a regex but aren't real)
+2. **Documentation showing example secret formats** (README explaining "API keys look like ghp_xxx...")
+3. **Migrating away from a leaked secret** that's been rotated and now needs `git-filter-repo`-style purging (the old value will appear in `--filter` operations)
+4. **gitleaks false positive** that's been added to `.gitleaks.toml` allowlist but cache hasn't refreshed
+
+**When the user passes `--skip-secret-scan`:**
+
+1. Print a prominent warning:
+   ```
+   ⚠️  SECRET SCAN BYPASSED — this commit will NOT be checked for leaked secrets.
+       Reason: <user must provide reason inline or in commit body>
+   ```
+2. **Require a reason** in the commit message body, prefixed `secret-scan-skip:`:
+
+   ```
+   feat(payments): add MP webhook validation
+
+   - Validate signatures with HMAC-SHA256
+   - Add timing-safe equal check
+
+   secret-scan-skip: test fixture in payments.spec.ts contains fake AWS key matching AKIA pattern
+   ```
+
+3. **Log the bypass** to `.merlin-core/thoughts/shared/incidents/secret-scan-bypass.log`
+   with timestamp, user, file list, reason
+4. **Even with the flag:** still run the scan in CI via `.github/workflows/secret-scan.yml`
+   (the `secret-safe-commit` skill installs this) — bypass is only local, not project-wide
+
+If the user invokes `--skip-secret-scan` without a reason, ABORT and ask for one.
+
+---
+
+## Commit Message Formats
+
+### Conventional (default)
+
+```
+type(scope): concise description of why
+
+- Detail about what changed
+- Another detail if needed
+```
+
+### Jira
+
+```
+PROJ-123: concise description of why
+
+- Detail about what changed
+- Another detail if needed
+```
+
+Where `PROJ-` comes from `operations.git.commit_prefix`.
+
+### Plain
+
+```
+Concise description of what changed and why
+
+- Detail about what changed
+- Another detail if needed
+```
+
+---
+
+## Rules
+
+- **NEVER bypass gitleaks without `--skip-secret-scan`** + explicit reason
+- **NEVER use `--no-verify`** unless explicitly requested by the user (separate from secret scan)
+- Never amend previous commits unless explicitly requested
+- Always create NEW commits
+- Stage specific files, not `git add -A`
+- Do NOT commit `.env` files or credentials — gitleaks catches most, but `.env*` should already be in `.gitignore`
+- If `operations.git.pre_commit_hooks` is defined, expect them to run — do not bypass
+- Respect `branch_strategy`: if gitflow, verify you're on the correct feature/develop branch, not main
+
+## Skill References
+
+- **`secret-safe-commit`** — provides gitleaks installation, `.gitleaks.toml` template, `.pre-commit-config.yaml`, and CI workflow
+- **`purge-leaked-secret`** — reactive runbook when a secret IS detected (rotate + clean + audit)
+- **`commit`** — alias of this command for backwards compatibility
+
+## Quick install for a project that doesn't have gitleaks yet
+
+```bash
+# One-time setup per project (the secret-safe-commit skill automates this):
+pip install pre-commit gitleaks
+pre-commit install
+
+# Verify it works:
+gitleaks protect --source . --staged --verbose
+```
+
+After install, every `git commit` runs gitleaks via pre-commit hook
+automatically AND `/safe-commit` runs it explicitly (defense in depth).

package/.merlin-core/commands/implementation/implement-plan.md

@@ -0,0 +1,129 @@
+---
+description: Implement technical plans from thoughts/shared/plans with phase-by-phase verification
+model: opus
+---
+
+# Implement Plan
+
+You are tasked with implementing an approved technical plan from `thoughts/shared/plans/`. Plans contain phases with specific changes and success criteria.
+
+## Getting Started
+
+When given a plan path:
+
+- Read the plan completely and check for existing checkmarks (- [x])
+- Read the original ticket and all files mentioned in the plan
+- **Read files fully** - never use limit/offset, you need complete context
+- Think deeply about how the pieces fit together
+- Create a todo list to track your progress
+- Start implementing if you understand what needs to be done
+
+If no plan path provided, ask for one.
+
+## Implementation Philosophy
+
+Plans are carefully designed, but reality can be messy. Your job is to:
+
+- Follow the plan's intent while adapting to what you find
+- Implement each phase fully before moving to the next
+- Verify your work makes sense in the broader codebase context
+- Update checkboxes in the plan as you complete sections
+
+When things don't match the plan exactly:
+
+```
+Issue in Phase [N]:
+Expected: [what the plan says]
+Found: [actual situation]
+Why this matters: [explanation]
+
+How should I proceed?
+```
+
+## Phase Execution
+
+For each phase:
+
+### 1. Read Context
+
+- Read all files mentioned in the phase
+- Understand the current state before making changes
+
+### 2. Implement Changes
+
+- Follow the plan's changes in order
+- Write clean, focused code
+- Don't add features not in the plan (Constitution IV: No Invention)
+
+### 3. Verify - Automated
+
+Run the automated success criteria:
+
+- `npm test` or equivalent
+- `npm run lint` or equivalent
+- Build checks
+
+Fix any failures before proceeding.
+
+### 4. Verify - Manual
+
+After automated verification passes, pause for human verification:
+
+```
+Phase [N] Complete - Ready for Manual Verification
+
+Automated verification passed:
+- [List automated checks that passed]
+
+Please perform the manual verification steps:
+- [List manual verification items from the plan]
+
+Let me know when manual testing is complete so I can proceed to Phase [N+1].
+```
+
+### 5. Update Progress
+
+- Check off completed items in the plan file using Edit
+- Update your TodoWrite list
+- Commit progress if appropriate
+
+## Resuming Work
+
+If the plan has existing checkmarks:
+
+- Trust that completed work is done
+- Start from the first unchecked phase
+- Verify the current state matches expectations before continuing
+
+## If You Get Stuck
+
+1. Read and understand all relevant code
+2. Consider if the codebase evolved since the plan was written
+3. Present the mismatch clearly and ask for guidance
+4. Use sub-tasks sparingly - mainly for targeted debugging
+
+## Follow-Through (Constitution VIII)
+
+Your goal is to complete every phase with quality. Give each phase your best effort.
+
+- After completing a phase, move to the next — maintain momentum through the plan
+- If a phase can't be completed, explain what's blocking it with specifics so it can be resolved
+- If context is getting long, create a /handoff documenting where you are and what remains — continuity matters
+- Update plan checkboxes as you go — they're how progress is tracked across sessions
+- After the final phase, verify your work (tests, lint, build) before declaring done
+- Quality over speed: a phase done well is worth more than two done carelessly
+
+## Handling Feedback During Implementation
+
+When receiving review feedback (from user, PR reviewer, or adversarial review):
+
+- **Clarify ALL before implementing** — If any feedback item is unclear, stop. Don't implement the clear ones and ask about the rest later. Items may be related; partial understanding leads to wrong implementations.
+- **Implementation order** — Fix blocking issues first, then simple fixes, then complex refactors. Test each fix individually before moving to the next.
+- **YAGNI check on suggestions** — Before implementing a reviewer's "add proper X" suggestion, grep the codebase to verify X is actually used. If nothing calls it, push back: "This isn't used. Remove it (YAGNI)?" (Constitution Article IV applies to review feedback too.)
+
+## Constitution Compliance
+
+- **Principle III**: You are implementing from a spec - follow it
+- **Principle IV**: Don't invent beyond what the plan specifies
+- **Principle V**: Run all quality checks before declaring phase complete
+- **Principle VII**: If the plan involves HIGH-stake actions, pause for approval

package/.merlin-core/commands/implementation/oneshot.md

@@ -0,0 +1,63 @@
+---
+description: Quick research-plan-implement cycle for small tasks (Folloni funnel compressed)
+model: opus
+---
+
+# Oneshot
+
+A compressed version of the Folloni funnel for small, well-defined tasks.
+Combines research, planning, and implementation in a single session.
+
+## When to Use
+
+- Small, focused changes (1-3 files)
+- Clear requirements that don't need extensive research
+- Bug fixes with known root cause
+- Simple feature additions
+
+## When NOT to Use
+
+- Complex features touching 5+ files → Use /plan instead
+- Unclear requirements → Use /research first
+- Architecture changes → Use full Folloni funnel
+
+## Process
+
+### Phase 1: Quick Research (2-3 minutes)
+
+- Read the relevant files FULLY
+- Spawn **scout** to find related files if needed
+- Understand the current implementation
+
+### Phase 2: Mini Plan (1-2 minutes)
+
+- Outline what changes are needed
+- List affected files
+- Define success criteria (automated + manual)
+- Present to user for quick approval
+
+### Phase 3: Implement
+
+- Make the changes
+- Run automated verification
+- Report results
+
+## Output Format
+
+```
+Oneshot: [Brief description]
+
+Research:
+- [Key finding 1]
+- [Key finding 2]
+
+Plan:
+- [ ] Change 1 in file.ts
+- [ ] Change 2 in other.ts
+
+Success Criteria:
+- Automated: [commands]
+- Manual: [verification steps]
+
+Proceeding with implementation...
+```

package/.merlin-core/commands/implementation/tdd.md

@@ -0,0 +1,152 @@
+---
+description: Enforces strict Red-Green-Refactor TDD discipline with git micro-commits at each phase
+model: opus
+version: "3.0.0"
+---
+
+# /tdd — Test-Driven Development Workflow
+
+Enforces the Red-Green-Refactor cycle. Prevents writing production code before the failing
+test exists. Each phase gets its own micro-commit for full traceability.
+
+## Usage
+
+```
+/tdd [feature-description]    → Start a new TDD cycle
+/tdd --continue               → Resume from current state (detects which phase you're in)
+/tdd --status                 → Show current cycle state without doing anything
+```
+
+## The Cycle
+
+```
+  ┌─────────────────────────────────────────────────────┐
+  │                   TDD CYCLE                         │
+  │                                                     │
+  │   ① RED          ② GREEN         ③ REFACTOR        │
+  │   Write the  →   Write minimal →  Improve code     │
+  │   failing        code to pass     while tests      │
+  │   test           the test         stay green       │
+  │                                                     │
+  │   git commit     git commit       git commit       │
+  │   test(red):     feat(green):     refactor:        │
+  │                                                     │
+  │         ↓ is the feature complete?                  │
+  │         ↑ NO → loop back to RED                     │
+  │         YES → done                                  │
+  └─────────────────────────────────────────────────────┘
+```
+
+## Phase Instructions
+
+### ① RED — Write the Failing Test
+
+1. Write a test that describes the desired behavior. Be specific — the test name should
+   read like a requirement: `it("should return 404 when user is not found")`
+2. Run the test suite and confirm the new test FAILS
+3. If the test passes without writing any code: the test is wrong or the feature already exists. Stop and investigate.
+4. Commit: `git commit -m "test(red): [description of what behavior is being tested]"`
+
+**Good test vs Bad test:**
+
+```typescript
+// GOOD — clear name, tests real behavior, one thing
+test("retries failed operations 3 times", async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error("fail");
+    return "success";
+  };
+  const result = await retryOperation(operation);
+  expect(result).toBe("success");
+  expect(attempts).toBe(3);
+});
+
+// BAD — vague name, tests mock not behavior
+test("retry works", async () => {
+  const mock = jest
+    .fn()
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce("ok");
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(2);
+});
+```
+
+**BLOCK:** Do not write any production code during this phase.
+
+**Test runner detection:**
+
+- `package.json` with jest/vitest → `npm test` or `npx vitest run`
+- `pytest` installed → `pytest [test_file]`
+- `go.mod` → `go test ./...`
+- `Cargo.toml` → `cargo test`
+
+### ② GREEN — Write Minimal Code to Pass
+
+1. Write the simplest code that makes the failing test pass. Resist the urge to make it
+   perfect — that's what Refactor is for.
+2. Run the test suite. The new test must pass. No existing tests must break.
+3. If any existing test breaks: fix the regression before proceeding. Do not commit broken tests.
+4. Commit: `git commit -m "feat(green): [description of the implementation]"`
+
+**BLOCK:** Do not refactor, rename, or improve code quality during this phase.
+**BLOCK:** Do not commit if any test is failing (including pre-existing tests).
+
+### ③ REFACTOR — Improve Without Changing Behavior
+
+1. Improve code quality: naming, structure, duplication, readability.
+2. Run tests after each meaningful change to ensure nothing broke.
+3. If a test breaks during refactor: you changed behavior, not just structure. Revert the change.
+4. Commit: `git commit -m "refactor: [description of the improvement]"`
+
+**BLOCK:** Do not add new behavior during this phase — that goes in the next RED cycle.
+
+### Cycle Completion Check
+
+After each REFACTOR commit, ask:
+
+> "Is the feature complete? Or does another behavior need to be tested?"
+
+- **Complete** → TDD cycle done. Run `/check` to run the full quality gate.
+- **More to build** → Start a new RED phase for the next behavior.
+
+## Guards
+
+| Situation                                        | Action                                                                                                                                              |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Production code written before RED commit exists | BLOCK — delete it, start over with the test. Code written before the test is unverified — keeping it as "reference" leads to testing-after, not TDD |
+| Test passes immediately without implementation   | STOP — investigate why (feature may already exist)                                                                                                  |
+| Committing GREEN with failing tests              | BLOCK — do not commit                                                                                                                               |
+| Adding new behavior during REFACTOR              | WARN — save it for the next RED cycle                                                                                                               |
+| Refactor breaks a test                           | STOP — revert the breaking change                                                                                                                   |
+
+## Example Cycle
+
+```
+Feature: "User profile endpoint returns 404 when user not found"
+
+RED:
+  test: GET /users/:id returns 404 when id doesn't exist
+  run: npm test → FAIL (404 handler not implemented)
+  commit: "test(red): user profile returns 404 for unknown id"
+
+GREEN:
+  code: add 404 check in getUserById handler
+  run: npm test → PASS
+  commit: "feat(green): return 404 when user not found in getUserById"
+
+REFACTOR:
+  improve: extract notFound() helper, improve error message
+  run: npm test → PASS
+  commit: "refactor: extract notFound helper in user controller"
+
+→ Done. Run /check for full quality gate.
+```
+
+## Integration
+
+- Extends [testing](../../skills/general/testing/SKILL.md) with enforcement mechanics
+- Micro-commits pair with [/commit](../git/commit.md) conventions
+- After TDD cycle is complete, run [/check](../review/check.md) for full gate validation