@alecsibilia/luca 13.0.0-alpha.1

package/dist/claude/skills/bug-diagnose/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: bug-diagnose
+description: "Disciplined diagnosis loop for hard bugs and performance regressions. Build a feedback loop first, then reproduce, hypothesise, instrument, fix, and clean up. Use when user says \"diagnose this\", \"debug this\", reports a bug, says something is broken/throwing/failing, describes a performance regression, or invokes /bug-diagnose."
+---
+
+# Bug Diagnose
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+## Phase 1 — Build a Feedback Loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause. If you don't, no amount of staring at code will save you.
+
+Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.
+
+### Ways to construct one — try in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e
+2. **Curl / HTTP script** against a running dev server
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network
+5. **Replay a captured trace** — save a real request/payload/event log; replay through the code path in isolation
+6. **Throwaway harness** — spin up a minimal subset of the system that exercises the bug code path
+7. **Property / fuzz loop** — if the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode
+8. **Bisection harness** — if the bug appeared between two known states, automate `git bisect run`
+9. **Differential loop** — run the same input through old-version vs new-version and diff outputs
+10. **HITL bash script** — last resort. If a human must click, structure the loop so captured output feeds back to you
+
+### Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow test scope)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash")
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network)
+
+### Non-deterministic bugs
+
+Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake is debuggable; 1% is not — keep raising the rate.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to the reproducing environment, (b) a captured artifact (HAR file, log dump, screen recording), or (c) permission to add temporary production instrumentation. **Do not proceed to Phase 2 without a loop.**
+
+## Phase 2 — Reproduce
+
+Run the loop. Watch the bug appear. Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure nearby
+- [ ] The failure is reproducible across multiple runs (or at a high enough rate to debug)
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing)
+
+Do not proceed until you reproduce the bug.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If \<X\> is the cause, then \<changing Y\> will make the bug disappear / \<changing Z\> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep."
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep.
+
+**Perf bugs**: logs are usually wrong. Establish a baseline measurement (timing harness, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + Regression Test
+
+Write the regression test **before the fix** — but only if there is a correct seam for it.
+
+A correct seam exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow, a regression test there gives false confidence. Note this — the architecture is preventing the bug from being locked down.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam
+2. Watch it fail
+3. Apply the fix
+4. Watch it pass
+5. Re-run the Phase 1 feedback loop against the original scenario
+
+## Phase 6 — Cleanup + Post-Mortem
+
+Required before declaring done:
+
+- [ ] Original repro passes (the bug is actually fixed)
+- [ ] All debug logs/probes removed (grep for your `[DEBUG-` tag)
+- [ ] Commit message explains **why** the bug happened and the fix
+- [ ] Open questions (if any) left as TODOs or follow-up issues

package/dist/claude/skills/choose/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: choose
+description: Choose between issue-driven development and Luca spec-driven workflow for a task.
+---
+
+<main>
+# Luca Choose Workflow
+
+Help users select the right development workflow for their task.
+
+## Two Development Paths
+
+This project supports two complementary workflows:
+
+| Workflow | Best For | Commands |
+|----------|----------|----------|
+| **Issue-Driven** | Quick fixes, single features | `/project:git/feature`, `bun commit` |
+| **Luca** | Complex initiatives, multi-phase | `/project-new`, `/phase-execute` |
+
+## Decision Matrix
+
+| Scenario | Recommended | Why |
+|----------|-------------|-----|
+| Quick bug fix | Issue workflow | Single commit, fast turnaround |
+| Single feature (1-3 files) | Issue workflow | Simple scope, direct PR |
+| New module/system (5+ phases) | Luca | Structured planning prevents context rot |
+| Greenfield project | Luca | Full roadmap with research phases |
+| Complex refactor | Luca | Phase-based execution with verification |
+| Same-day completion | Issue workflow | No planning overhead needed |
+| Multi-session work | Luca | State machine preserves context across sessions |
+
+## Process
+
+### Step 1: Ask About the Task
+
+Use AskQuestion tool:
+
+- header: "Workflow Selection"
+- question: "What kind of work are you doing?"
+- options:
+  - "Bug fix or small enhancement" → Issue workflow
+  - "Single feature (1-3 files changed)" → Issue workflow
+  - "New project or major initiative" → Luca
+  - "Complex refactor (many files)" → Luca
+  - "Not sure, help me decide" → Continue to Step 2
+
+### Step 2: Gather More Context (if needed)
+
+Ask clarifying questions:
+
+- How many phases/stages do you envision?
+- Will this take multiple sessions to complete?
+- Do you need structured research before implementation?
+
+### Step 3: Route to Workflow
+
+**For Issue Workflow:**
+
+```
+## Recommended: Issue-Driven Workflow
+
+This task is well-suited for the issue workflow.
+
+**Next Steps:**
+1. Create or find a GitHub issue
+2. Run: `/project:git/feature {issue}--{description}`
+3. Implement with `bun commit` for each change
+4. Create PR when done
+
+**Commands:**
+- `/project:git/feature` — Create feature branch
+- `/project:git/commit` — Conventional commit
+- `/project:git/pr` — Create pull request
+```
+
+**For Luca Workflow:**
+
+```
+## Recommended: Luca Workflow
+
+This task benefits from structured planning and phased execution.
+
+**Next Steps:**
+1. Run: `/project-new` to initialize
+2. Answer questions to build roadmap
+3. Execute phases with `/phase-execute`
+
+**Commands:**
+- `/project-new` — Initialize project with roadmap
+- `/progress` — Check current status
+- `/help` — See all Luca commands
+```
+
+## Key Differences
+
+| Aspect | Issue Workflow | Luca |
+|--------|----------------|------|
+| Planning | `.cursor/plans/` | `.luca/` |
+| Commits | `type(scope): #issue desc` | `type(phase-plan): #issue desc` |
+| Branch | `{issue}--{description}` | `{issue}--{description}` |
+| State | Git history | State machine (.luca/state.json) + Git |
+| Verification | Manual testing | Automated phase verification |
+
+## Success Criteria
+
+- [ ] User's task complexity understood
+- [ ] Appropriate workflow recommended
+- [ ] Next steps clearly explained
+- [ ] User ready to proceed
+
+## Next Steps
+
+This skill helps you decide between workflows. After choosing:
+
+| Choice | Next Command |
+|--------|--------------|
+| Issue-driven | `/lu [TICKET-ID]` or `/lu {task}` |
+| Luca | `/project-new` |
+| Quick task | `/quick` |
+
+**Common follow-ups:**
+- `/help` — Review all available commands
+- `/progress` — Check existing project status
+</main>

package/dist/claude/skills/gh-issue-triage/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gh-issue-triage
+description: "Pull open GitHub issues into the MuninnDB todo backlog for pipeline execution. Filters out issues labeled `skip-triage`, deduplicates against existing todos, and links each todo back to its originating issue so the PR can close it on merge. Use when user says \"triage issues\", \"pull in issues\", \"import issues\", \"sync issues to todos\", or invokes /gh-issue-triage."
+---
+
+# GH Issue Triage
+
+Pull open GitHub issues into the **MuninnDB todo backlog** so the Luca pipeline can pick them up. Each issue becomes a `todo:*` memory; when the pipeline ships a PR it closes the originating issue automatically via `Closes #N`.
+
+## Process
+
+### 1. Fetch open issues
+
+```bash
+gh issue list --state open --json number,title,body,labels,assignees,createdAt --limit 100
+```
+
+If no GitHub remote is detected, stop and tell the user.
+
+### 2. Load existing todos (for dedup)
+
+Run `luca todo list`. It prints a `mcp__muninn__muninn_recall` instruction blob — execute it exactly as returned. Each recalled memory's `content` is JSON conforming to `TodoSchema`; collect every existing todo's `source` field. This is the dedup set for step 5.
+
+### 3. Filter
+
+Remove issues that should not become todos:
+
+- **`skip-triage`** label — explicitly excluded from automatic triage
+- **Pull requests** — `gh issue list` may include PRs on some repos; filter by `pull_request` field if present
+- **Already triaged** — drop any issue whose `gh-issue-#<N>` already appears in the dedup set from step 2
+
+If `$ARGUMENTS` contains filter terms (e.g. a label name, milestone, or assignee), apply them:
+
+```bash
+gh issue list --state open --label "<label>" ...
+```
+
+### 4. Present candidates
+
+Show the filtered list to the user:
+
+```
+## Issues Ready for Triage
+
+1. #42 — Add webhook support [enhancement] (2 days ago)
+2. #38 — Login fails on Safari [bug] (5 days ago)
+3. #35 — Refactor auth module [refactor] (1 week ago)
+
+Skipped: 2 issues (skip-triage), 1 already in backlog
+
+Import all, or select by number?
+```
+
+Wait for the user to confirm which issues to import. Accept "all" or a comma-separated list of numbers.
+
+### 5. Create todos
+
+For each approved issue, stage the `metadata` object in a JSON file and run `luca todo add`:
+
+```
+# /tmp/luca-todo-meta.json:
+# { "priority": "<high|medium|low>", "area": "<ui|api|infra|...>" }
+luca todo add \
+  --title "<issue title>" \
+  --body "> GitHub Issue: #<N> — <url>
+
+<issue body, trimmed to essentials>" \
+  --source "gh-issue-#<N>" \
+  --metadata-file /tmp/luca-todo-meta.json
+```
+
+- **`--source`** is `gh-issue-#<N>` — the link back to the originating issue. It carries the issue number through the entire pipeline.
+- **`priority`** is inferred from labels (`critical`/`bug` → `high`, `enhancement` → `medium`, unlabeled → `medium`) and goes in the metadata file.
+- **`area`** is inferred from labels when recognizable (`ui`, `api`, `infra`) and goes in the metadata file.
+
+`luca todo add` validates the input and prints a `mcp__muninn__muninn_remember` instruction blob — execute that instruction **exactly as returned** to persist the todo. The todo `id` is derived from the title (kebab-slug).
+
+### 6. Report
+
+Print a summary of what was imported:
+
+```
+## Triage Complete
+
+Created 3 todos from GitHub issues:
+  - #42 → todo: add-webhook-support (pending)
+  - #38 → todo: login-fails-on-safari (pending, priority: high)
+  - #35 → todo: refactor-auth-module (pending)
+
+Skipped: 1 duplicate (#31 already exists as a todo)
+
+Next: run /lu to start working through the backlog.
+```
+
+## Closing the loop
+
+When work ships a PR for a todo whose `source` is `gh-issue-#<N>`, the PR body must include `Closes #<N>` so the issue closes on merge. The `gh-prepare` skill reads the todo's `source` field to render that line — the `source` is the carrier that links issue → todo → PR.

package/dist/claude/skills/gh-pr-address/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: gh-pr-address
+description: Address PR review comments — fetch, filter stale, categorize, fix, respond, regression-check.
+---
+
+# /gh-pr-address
+
+Address PR review comments by fetching them, dropping stale ones, categorizing by severity, implementing fixes, posting replies, and verifying the fix iteration introduced no regressions.
+
+## Parse arguments
+
+Parse `$ARGUMENTS` for:
+
+- A **PR number** (e.g. `42`) or **PR URL** (e.g. `https://github.com/owner/repo/pull/42`)
+- `--dry-run` — show categorized comments and planned fixes without executing
+- `--skip-validation` — skip categorization; treat all comments as actionable
+- `--no-respond` — fix issues but don't post reply comments
+
+If no PR number or URL is provided, detect it from the current branch:
+
+```bash
+gh pr view --json number,url
+```
+
+Resolve `<repo_vault>` from `.luca/config.json` → `muninn.vault`, falling back to `"default"`.
+
+## Step 1 — Fetch PR data
+
+Fetch all reviews and review comments:
+
+```bash
+gh pr view <number> --json reviews,comments,reviewDecision,title,body,number,url
+gh api repos/{owner}/{repo}/pulls/<number>/comments --paginate
+```
+
+Group the results:
+
+- **Review comments** — inline code comments with file/line context (the `gh api pulls/<n>/comments` shape).
+- **General comments** — conversation-level feedback.
+- **Duplicates** — the same concern on different lines; group by content similarity and track every comment id in the group.
+
+Build a comment map with fields: `commentId, author, body, file, line, inReplyTo, isDuplicate, duplicateGroupId`.
+
+**Snapshot the iteration boundary.** Record the current `git rev-parse HEAD` SHA as `iterationStartSha` and the current time as `iterationStartTime` (ISO 8601). Step 7 uses the SHA to compute which paths the iteration modified and the timestamp to filter newly-created comments.
+
+## Step 1.5 — Filter stale comments
+
+Comments filed against an earlier commit may already be addressed by later fix commits on the branch. Acting on them wastes iteration cycles.
+
+Run the stale-comment filter on the **review comments** (the raw `gh api pulls/<n>/comments` objects — each carries `id, path, line, original_line, commit_id, original_commit_id, diff_hunk, body, in_reply_to_id?, user?`). Stage the review comments array in a JSON file, then run `luca pr-review filter-stale --file`:
+
+```
+# /tmp/luca-pr-comments.json holds the review comments array from Step 1
+luca pr-review filter-stale --file /tmp/luca-pr-comments.json
+```
+
+The command partitions them into four buckets:
+
+- **`actionable`** — cited code still exists at the same location. Continue with categorization for these.
+- **`stale`** — cited code was rewritten, removed, or relocated beyond the drift tolerance. **Skip categorization.** When responding (Step 5), reply that the comment is stale and point at the commit that addressed the underlying code.
+- **`replies`** — comments with `in_reply_to_id` set; pass through, not first-class findings.
+- **`unknown`** — could not be re-anchored; treat conservatively as actionable.
+
+Append a note to the Step 2 audit summary: `Stale: <n> comments (skipped from categorization)`.
+
+## Step 2 — Categorize comments
+
+Unless `--skip-validation` is set, classify each unique actionable comment (deduplicated):
+
+| Category | Action | Examples |
+|----------|--------|---------|
+| **security** | Must fix | Vulnerabilities, injection, credential exposure |
+| **bug** | Must fix | Logic errors, regressions, broken behavior |
+| **requirement** | Must fix | Missing acceptance criteria, spec violations |
+| **style** | Should fix | Naming, formatting, established pattern violations |
+| **improvement** | Should fix | Better approach, DX, readability |
+| **question** | Respond only | Clarification requests, design rationale questions |
+| **nit** | Optional | Trivial preferences, minor suggestions |
+| **praise** | Respond only | Positive feedback |
+
+Present a summary:
+
+```
+## PR #<number> Comment Audit
+
+Must Fix: N comments (security: N, bug: N, requirement: N)
+Should Fix: N comments (style: N, improvement: N)
+Respond Only: N comments (question: N, praise: N)
+Nit: N comments
+Stale: N comments (skipped from categorization)
+
+Total: N unique comments (N duplicates grouped)
+```
+
+If `--dry-run`, stop here.
+
+## Step 2.5 — Detect cross-perspective convergence
+
+When two or more independent reviewer perspectives flag the same location, that location is materially more likely to be a real issue. Auto-promote severity so converged findings are treated as must-fix.
+
+Build a `findings` array — one entry per actionable comment, plus any findings from other perspectives this iteration has access to. If a pipeline phase is active, include the `luca-reviewer` MUST-FIX/SHOULD-FIX entries from `.luca/phases/<NN-slug>/audits/*.md`. Map each to:
+
+```
+{
+  id:          <stable id, e.g. comment id or "luca-reviewer:<n>">,
+  perspective: <who produced it, e.g. "Copilot", "luca-reviewer">,
+  path:        <file path>,
+  line:        <line number>,
+  severity:    <"must-fix" | "should-fix" | "nit" | "style" | "improvement" | ...>,
+  category:    <"security" | "bug" | "style" | ...>,
+  summary:     <short description>
+}
+```
+
+Run convergence detection. Stage the findings array in a JSON file, then run `luca pr-review detect-convergence --file`:
+
+```
+# /tmp/luca-pr-findings.json holds the findings array
+luca pr-review detect-convergence --file /tmp/luca-pr-findings.json --line-tolerance 2
+```
+
+For each entry in the returned `report.promotions`:
+
+- Find the corresponding categorized comment in your audit map.
+- Update its severity to **must-fix** (regardless of its original severity), preserving the original category. Add a note: `Promoted via convergence with <other perspectives>`.
+- Surface it in the audit summary: `Converged: <n> findings promoted to must-fix via 2+ perspectives`.
+
+Continue to Step 3 with the promoted findings.
+
+## Step 3 — Plan fixes
+
+For comments with severity **must fix** and **should fix**:
+
+1. Group by file for efficient execution.
+2. Determine the fix approach for each comment.
+3. Order by severity: security → bug → requirement → style → improvement.
+
+## Step 4 — Execute fixes
+
+Spawn **`luca-executor`** subagents (one per file group) via the `Agent` tool. Each subagent receives:
+
+- The file path and the relevant comment details (body, line, category).
+- Instructions to fix each issue and commit using the project's commit convention. Read it first by running `luca preferences read` and using the `commits` section (`convention`, `types`, `scopes`, `trailers`, `subjectMaxLength`). Reference the PR number per `commits.trailers.issueRef` when set; the executor adds the `Co-Authored-By` trailer automatically when `commits.trailers.coAuthor === true`.
+
+After all executor subagents complete, run a type check:
+
+```bash
+bunx --bun tsc --noEmit
+```
+
+If the type check fails, fix the errors before proceeding.
+
+## Step 5 — Respond to comments
+
+Unless `--no-respond` is set, post replies to **every** PR comment thread (including all duplicate ids in each group):
+
+- **Fixed comments** → reply with what changed and which commit addresses it.
+- **Stale comments** → reply that the comment is stale and point at the commit that already addressed the code.
+- **Question comments** → reply with an answer based on codebase context.
+- **Nit comments** → acknowledge briefly (applied or noted).
+- **Praise comments** → thank and acknowledge briefly.
+
+Post inline review-comment replies:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<number>/comments/<commentId>/replies -f body="<reply>"
+```
+
+Post top-level (conversation) replies:
+
+```bash
+gh api repos/{owner}/{repo}/issues/<number>/comments -f body="<reply>"
+```
+
+## Step 6 — Push and verify
+
+1. Push the fixes: `git push`
+2. Verify zero unreplied threads remain:
+
+   ```bash
+   gh api repos/{owner}/{repo}/pulls/<number>/comments --paginate
+   ```
+
+   Check that every comment thread has a reply. Report any gaps.
+
+## Step 7 — Iteration-N regression check
+
+Fix commits sometimes introduce new issues the original review didn't flag. Catch them now instead of paying for another full review pass.
+
+1. **Re-fetch all PR comments:**
+
+   ```bash
+   gh api repos/{owner}/{repo}/pulls/<number>/comments --paginate
+   ```
+
+   If the PR has automated reviewer hooks (Copilot, CodeRabbit, etc.) that re-run on push, allow a brief settle window (~30s) before re-fetching.
+
+2. **Build before/after finding arrays.** The `before` array is the `findings` array from Step 2.5 (pre-iteration state). The `after` array is built the same way from the freshly-fetched comments — include only comments with `created_at >= iterationStartTime` to filter out persistent prior findings.
+
+3. **Run the regression check** (it computes touched paths from the SHA range via `git diff`). Stage the full payload object in a JSON file, then run `luca pr-review regression-check --file`:
+
+   ```
+   # /tmp/luca-pr-regression.json holds:
+   # {
+   #   "before":   <pre-iteration findings>,
+   #   "after":    <post-iteration findings>,
+   #   "from_sha": "<iterationStartSha>",
+   #   "to_sha":   "HEAD"
+   # }
+   luca pr-review regression-check --file /tmp/luca-pr-regression.json
+   ```
+
+4. **Handle the verdict.**
+
+   - No regressions (exit `0`, `report.regressions` empty) → iteration complete. Report `<n> resolved, <n> unchanged, <n> new on untouched paths` in the final summary.
+   - Regressions present (exit `1`, `report.regressions` non-empty) → fix commits introduced new findings. **Do not declare the iteration complete.** Re-enter Step 3 (Plan fixes) with `report.regressions` as the input set. The regression cycle is bounded — if 3 consecutive iterations fail this check, escalate to the user with a summary of what's regressing and pause the loop.
+
+## Step 8 — Store learnings
+
+Store **recurring patterns** in MuninnDB (skip one-off fixes). The `pattern:*` prefix routes to the `"default"` vault per the vault-routing rule:
+
+```
+mcp__muninn__muninn_remember_batch({
+  vault: "default",
+  memories: [
+    {
+      concept: "pattern:pr-review-<category>",
+      content: "<description of the recurring review-feedback pattern>",
+      tags: ["pr-review", "<category>"]
+    }
+  ]
+})
+```
+
+$ARGUMENTS