@alecsibilia/luca 13.0.0-alpha.1

package/dist/claude/.claude/commands/gh-pr-address.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

package/dist/claude/.claude/commands/gh-prepare.md

@@ -0,0 +1,12 @@
+---
+name: gh-prepare
+description: Ship committed work — ensure a changeset, push the feature branch, open a draft PR.
+---
+
+# /gh-prepare
+
+Activate the `gh-prepare` skill to ship committed work: ensure a changeset exists, push the current feature branch to the remote, and open (or update) a draft PR that links its tracking issue with `Closes #<issue>` for auto-linking.
+
+Works standalone or inside the pipeline. Run the `gh-prepare` skill now. Optional arguments — free-form hints (issue number, PR title, base branch):
+
+$ARGUMENTS

package/dist/claude/.claude/commands/grill-me.md

@@ -0,0 +1,12 @@
+---
+name: grill-me
+description: Stress-test a plan or design by walking each branch of the decision tree.
+---
+
+# /grill-me
+
+Activate the `grill-me` skill to interview you relentlessly about a plan or design — walking each branch of the decision tree, surfacing unstated assumptions, and offering an ADR only when a choice is hard to reverse, surprising, and carries a real trade-off.
+
+Run the `grill-me` skill now. The plan or design to grill:
+
+$ARGUMENTS

package/dist/claude/.claude/commands/lu-review.md

@@ -0,0 +1,51 @@
+---
+name: lu-review
+description: Re-enter the Luca pipeline at the review step to audit completed work.
+---
+
+# /lu-review
+
+Run the **review** step against the active phase — a structured multi-perspective audit of executed code. Use this after `/phase-execute` + verification, or to re-audit a phase before closing it.
+
+You are orchestration only: read state, run the reviewers, let them persist their audits with the `Write` tool.
+
+## Step 0 — Read state
+
+Run `luca state read`. The review step has exactly one legal entry: `verify → review`. There is no bypass — `luca state advance` rejects illegal jumps.
+
+- `pipelineStep === "verify"` → run `luca state advance --to-step review`, then proceed.
+- `pipelineStep === "review"` → already there, proceed.
+- anything else → STOP. Tell the user the pipeline must reach `verify` before review can run, and point them at `/lu` to drive it there. Do not attempt to force the transition.
+
+Run `luca phase current` to get the active slug. If no phase is active, abort.
+
+## Run the reviewers
+
+Spawn the `luca-reviewer` subagent via the `Agent` tool — once per perspective, in parallel:
+
+- `architect` — structural correctness, dependency direction, API surface
+- `dx` — readability, error messages, ergonomics
+- `security` — input validation, injection, secret handling
+- `simplification` — unnecessary complexity, dead code
+- `test-quality` — vacuous mocks, presence-only assertions, coverage-by-existence
+
+Pass each reviewer its assigned perspective and the active phase slug. Each reviewer persists its own audit by writing `audits/<reviewer>.md` with the `Write` tool to the canonical phase path (the stage-gate hook only permits that write in the `review` step).
+
+Scale the perspective set to complexity: TRIVIAL/SIMPLE may run only `architect` + `security`; MODERATE+ runs the full set.
+
+## Aggregate
+
+When all reviewers return, summarize for the user:
+
+- Total MUST-FIX / SHOULD-FIX / NOTE counts across audits
+- Whether any reviewer returned `REQUEST_CHANGES`
+
+If there are MUST-FIX findings, the phase is not ready to advance — direct the user back to `/phase-execute` to address them (the `verify → checks → execute` loop-back path). If all reviewers APPROVE, advance with `luca state advance --to-step learn`.
+
+## What you must NOT do
+
+- Do NOT force a transition into `review` from a non-`verify` state. Honor the no-bypass policy.
+- Do NOT write audit files yourself — the reviewers write `audits/<reviewer>.md` with the `Write` tool to the canonical path; the hook blocks any other write.
+- Do NOT fix the findings yourself in this skill. Review reports; execute fixes.
+
+$ARGUMENTS

package/dist/claude/.claude/commands/lu.md

@@ -0,0 +1,75 @@
+---
+name: lu
+description: Start (or resume) the Luca autonomous development pipeline for a request.
+---
+
+# /lu
+
+The unified entry point for the Luca pipeline. `/lu <request>` takes a development request and drives it through the full pipeline: triage → research → discuss → architect → plan → plan-review → execute → checks → verify → review → learn → milestone.
+
+You are the **orchestrator**. You do not write code or planning artifacts directly — you read state, run each step (delegating to its skill or subagent), and advance the pipeline.
+
+## Step 0 — Read state
+
+Run `luca state read`. Branch on `pipelineStep`:
+
+- `idle` or `complete` → fresh start. Go to **Triage**.
+- anything else → the pipeline is mid-flight. Skip triage, go straight to **Pipeline loop** and resume from the current step.
+
+If the user passed a request but the pipeline is already mid-flight, surface that to the user and ask whether to resume the current run or finish it first — do NOT silently discard either.
+
+## Triage
+
+Triage runs once, at the start of a run. It is inline here — there is no separate triage skill.
+
+1. **Classify complexity.** Read the request. Pick one of `TRIVIAL | SIMPLE | MODERATE | COMPLEX | CRITICAL` based on file count, scope, and risk. There is no CLI command to persist complexity — record it in your reasoning and pass it to every subagent you spawn (the model-routing table keys off it).
+2. **Build the roadmap.** Decompose the request into ordered phases. Each phase is one deliverable unit. Stage the phases array in a JSON file, then run `luca roadmap create --file`:
+   ```
+   # /tmp/luca-roadmap.json:
+   # [
+   #   { "name": "<kebab-or-prose name>", "deps": [], "complexity": "<level>" },
+   #   ...
+   # ]
+   luca roadmap create --file /tmp/luca-roadmap.json
+   ```
+   For a single-deliverable request, that is a one-phase roadmap. `luca roadmap create` is only legal in `idle`/`triage` — it resets `currentPhase` to 0.
+3. **Advance** `idle → triage → research` via two `luca state advance --to-step <step>` calls.
+
+## Pipeline loop
+
+Repeat until `pipelineStep` is `complete`:
+
+1. Run `luca state read` to get the current `pipelineStep`.
+2. Run the step using the table below.
+3. Advance to the next step with `luca state advance --to-step <step>`. Transitions are validated against the pipeline-transitions table — illegal jumps are rejected.
+
+| Step          | How to run it                                                              |
+|---------------|----------------------------------------------------------------------------|
+| `research`    | Spawn `luca-researcher` (Agent tool). Persist its output by writing `research.md` with the `Write` tool to the canonical phase path (get the dir from `luca phase current`). |
+| `discuss`     | Invoke the `/phase-discuss` skill.                                         |
+| `architect`   | Lightweight synthesis: read research + context, confirm the plan-ready brief. Advance to `plan`. |
+| `plan`        | Invoke the `/phase-plan` skill.                                            |
+| `plan-review` | Spawn `luca-plan-reviewer` (Agent tool). On `NEEDS_REVISION`, loop back to `plan`. |
+| `execute`     | Invoke the `/phase-execute` skill.                                         |
+| `checks`      | Run `luca checks run --file <commands.json>` with the project's typecheck (and tests, if present). On failure, loop back to `execute`. |
+| `verify`      | Spawn `luca-verifier` (Agent tool). On `recommendation: fix`, loop back to `checks`; on `escalate`, stop and surface to the user. |
+| `review`      | Spawn `luca-reviewer` (Agent tool) — one per perspective, in parallel.     |
+| `learn`       | Spawn `luca-learner` (Agent tool). Then: more phases remain → advance to `plan` for the next phase; last phase → advance to `milestone`. |
+| `milestone`   | Invoke the `/milestone-new` skill to close out, or advance to `complete` if no milestone bookkeeping is needed. |
+
+## Oversight
+
+Read `oversight` from `luca state read`:
+
+- `full-auto` — run the whole loop without pausing.
+- `checkpoint` — pause after `plan-review`, `verify`, and `learn` for user confirmation.
+- `human-in-loop` — pause after every step.
+
+## What you must NOT do
+
+- Do NOT write code directly. Phase artifact files are written with the `Write` tool to their canonical path by a subagent or `/phase-*` skill; structured `.luca/` mutations go through the `luca` CLI. The stage-gate hook blocks any other direct write.
+- Do NOT skip steps. The pipeline-transitions table is the contract; `luca state advance` enforces it. There is no bypass.
+- Do NOT re-triage a mid-flight pipeline. Resume from the current step instead.
+- Do NOT commit. Commits happen only in the finalizing flow, never inside `/lu`.
+
+$ARGUMENTS

package/dist/claude/.claude/commands/luca-init.md

@@ -0,0 +1,14 @@
+---
+name: luca-init
+description: Seed project preferences (branching, commits, PR, release, tracker conventions) for this repo.
+---
+
+# /luca-init
+
+Activate the `luca-init` skill to probe the repository and seed its project preferences — branch naming, commit conventions, PR templates, release tooling, and issue tracker.
+
+This is distinct from the `luca init` CLI command (`npx luca init`), which wires up the per-project `.claude/` hooks. `/luca-init` runs *after* that, to capture the repo's working conventions into `.luca/config.json` (via the `luca preferences write` CLI) so the pipeline emits work that matches the project's existing style.
+
+Run the `luca-init` skill now. Optional arguments — `--auto` for non-interactive mode, or free-form hints about repo conventions:
+
+$ARGUMENTS

package/dist/claude/.claude/commands/luca-telemetry-report.md

@@ -0,0 +1,12 @@
+---
+name: luca-telemetry-report
+description: Aggregate .luca/telemetry/*.jsonl across recent runs and emit a markdown report. Read-only — never mutates state.
+---
+
+# /luca-telemetry-report
+
+Activate the `luca-telemetry-report` skill to aggregate the per-run event logs under `.luca/telemetry/*.jsonl` across recent runs and emit a markdown report summarising step durations, model usage, and pipeline outcomes. Strictly read-only — it never mutates workflow state or writes into the `.luca/` contract.
+
+Run the `luca-telemetry-report` skill now. Optional arguments (`--runs <N>` default 10, `--since <ISO-date>`, `--vault <name>`):
+
+$ARGUMENTS

package/dist/claude/.claude/commands/memory-audit.md

@@ -0,0 +1,12 @@
+---
+name: memory-audit
+description: Paginated LLM-judged retro-pass over a MuninnDB vault — classify trust tiers, write a resumable cursor, emit a per-run report.
+---
+
+# /memory-audit
+
+Activate the `memory-audit` skill to run a paginated, LLM-judged retro-pass over a MuninnDB vault: classify each memory's trust tier (inferred vs. verified), write a resumable cursor so a long audit can be continued across runs, and emit a per-run report.
+
+Run the `memory-audit` skill now. Optional arguments (`--dry-run` default, `--apply`, `--vault <name>`, `--resume`, `--limit <n>`, `--auto`):
+
+$ARGUMENTS

package/dist/claude/.claude/commands/milestone-new.md

@@ -0,0 +1,122 @@
+---
+name: milestone-new
+description: Start a new milestone cycle — gather goals, optionally research, define requirements, build the roadmap.
+---
+
+# /milestone-new
+
+Start a new milestone cycle. This is the brownfield equivalent of project initialization — use it when beginning a fresh body of work on an existing project.
+
+## Parse arguments
+
+Parse `$ARGUMENTS` for:
+- An optional **milestone name** (e.g. `"v2 API Redesign"`)
+- An optional **version** (e.g. `v2`, `v3`)
+- `--skip-research` — skip the research step
+
+## Step 1 — Load context
+
+1. Recall project identity from MuninnDB: `mcp__muninn__muninn_recall({ vault: "<repo_vault>", context: ["brain:project-identity"], mode: "semantic" })`.
+2. Recall prior milestones: `mcp__muninn__muninn_recall({ vault: "<repo_vault>", context: ["milestone:"], mode: "recent" })`.
+3. Run `luca state read` to check the pipeline status.
+
+Resolve `<repo_vault>` from `.luca/config.json` → `muninn.vault`, falling back to `"default"`.
+
+If the pipeline is mid-flight (`pipelineStep` is not `idle` or `complete`), warn the user that starting a new milestone resets pipeline state, and confirm before proceeding.
+
+## Step 2 — Gather milestone goals
+
+Ask the user (use `AskUserQuestion` where there are real choices):
+- What should this milestone accomplish?
+- Key features or changes?
+- Constraints or deadlines?
+- Target scope — a small focused change or a large feature set?
+
+Compile the answers into a structured goal list.
+
+## Step 3 — Determine version
+
+- If prior milestones exist (from the Step 1 recall), suggest the next sequential version.
+- If a version was passed in arguments, use that.
+- If there are no prior milestones, start at `v1`.
+
+Confirm the version with the user.
+
+## Step 4 — Persist the milestone
+
+Store the milestone in MuninnDB (the `milestone:*` prefix routes to the **repo** vault per the vault-routing rule):
+
+```
+mcp__muninn__muninn_remember({
+  vault: "<repo_vault>",
+  concept: "milestone:v<version>-goals",
+  content: "<structured goal list + scope + constraints>"
+})
+```
+
+There is no `.luca/PROJECT.md` — project identity lives in the MuninnDB brain tree, and milestone goals live in the `milestone:*` memory above. Do not create root-level planning files; the `.luca/` contract does not allow them.
+
+## Step 5 — Research (optional)
+
+Unless `--skip-research` is set, for each major feature area spawn the `luca-researcher` subagent via the `Agent` tool with milestone-aware context (project brief + goal list + the feature to research).
+
+Store each research summary in MuninnDB under `research:<feature-slug>` in the repo vault. Per-phase `research.md` files are written later by the pipeline once phases exist — milestone-level research is memory-only.
+
+Present a summary of key findings to the user.
+
+## Step 6 — Define requirements
+
+Based on the goals (and research, if run), present the feature list with suggested scope:
+- **Must have** — core requirements that define the milestone
+- **Should have** — important, not blocking
+- **Nice to have** — stretch goals
+
+Let the user adjust. Fold the agreed requirement list into the milestone memory from Step 4 (re-`remember` with the requirements appended) — there is no separate requirements file.
+
+## Step 7 — Build the roadmap
+
+Organize the requirements into ordered phases by dependency and priority. Stage the phases array in a JSON file, then run `luca roadmap create --file`:
+
+```
+# /tmp/luca-roadmap.json:
+# [
+#   { "name": "<phase name>", "deps": [...], "complexity": "<TRIVIAL|SIMPLE|MODERATE|COMPLEX|CRITICAL>" },
+#   ...
+# ]
+luca roadmap create --file /tmp/luca-roadmap.json
+```
+
+`luca roadmap create` is only legal in `idle`/`triage`; it resets `currentPhase` to 0 and sets `totalPhases`. If the pipeline was mid-flight and the user confirmed the reset in Step 1, run `luca workflow reset --confirm` first to return to a clean idle state.
+
+## Step 8 — GitHub tracking
+
+Offer three options:
+
+1. **New issue + branch** — `gh issue create --title "v<version>: <name>" --body "<description>"`, then create and push a feature branch.
+2. **Continue on existing** — comment on the open issue noting the new milestone, keep the current branch.
+3. **No tracking** — skip (warn that no PR will be auto-created later).
+
+## Step 9 — Done
+
+Report completion:
+
+```
+## Milestone v<version>: <name> — Initialized
+
+Roadmap: <N> phases. Pipeline reset to idle.
+Next: /lu <describe the first phase of work>
+```
+
+Record the initialization in MuninnDB and promote it to the verified tier:
+
+```
+mcp__muninn__muninn_remember({
+  vault: "<repo_vault>",
+  concept: "milestone:v<version>-initialized",
+  content: "Milestone v<version> '<name>' initialized: <N> requirements across <N> phases. Goals: <brief>."
+})
+```
+
+Capture the returned id and call `mcp__muninn__muninn_trust({ id: <id>, trust: "verified", vault: "<repo_vault>" })` — this is a user-confirmed milestone, so it belongs at the verified tier.
+
+$ARGUMENTS

package/dist/claude/.claude/commands/phase-discuss.md

@@ -0,0 +1,45 @@
+---
+name: phase-discuss
+description: "Drive the \"discuss\" pipeline step — gather user decisions for the active phase and persist them as context.md."
+---
+
+# /phase-discuss
+
+You are running the **discuss** step of the luca pipeline. The current phase has been triaged and researched; now you need user decisions before planning can begin.
+
+## Preconditions
+
+Before doing anything, confirm we're in the right state:
+
+1. Run `luca state read` and verify `pipelineStep` is either `research` (transitioning forward) or `discuss` (already advanced).
+2. If `pipelineStep` is `research`, run `luca state advance --to-step discuss` to enter this step.
+3. Run `luca phase current` to get the active phase slug and directory. If `active` is false, abort and ask the user to set the roadmap first.
+
+If the state is anything else, surface a clear error to the user instead of guessing.
+
+## Gather decisions
+
+Ask the user 1–4 focused questions to resolve open scope/design decisions for the phase. Reference the research findings (read from `.luca/phases/<slug>/research.md` via the `Read` tool) so the questions are grounded.
+
+Use the `AskUserQuestion` tool when there are concrete choices with trade-offs. Keep questions focused — no padding.
+
+## Persist context
+
+When the user has answered, write the consolidated context with the `Write` tool to the canonical path. Use the `dir` field from `luca phase current`; the context path is `<dir>/context.md`:
+
+```
+Write tool → <dir>/context.md
+content: "<markdown summary of decisions>"
+```
+
+The stage-gate hook only permits this `Write` to `<dir>/context.md` while `pipelineStep === "discuss"` — any other path or step is blocked.
+
+## Advance
+
+When context.md is written, run `luca state advance --to-step architect` so the next step can begin.
+
+## What you must NOT do
+
+- Do NOT write `context.md` to any path other than `<dir>/context.md`, or via `Edit` — the hook blocks every other `.luca/` write.
+- Do NOT skip the question-asking step just because you have an opinion. The point of `/phase-discuss` is to surface user decisions, not yours.
+- Do NOT write code in this step. Code writes are blocked by the stage-gate in PLANNING phases.

package/dist/claude/.claude/commands/phase-execute.md

@@ -0,0 +1,39 @@
+---
+name: phase-execute
+description: "Drive the \"execute\" pipeline step — implement the phase plan with per-task commits and verification."
+---
+
+# /phase-execute
+
+You are running the **execute** step. The plan exists and has been reviewed. Your job is to implement it.
+
+## Preconditions
+
+1. Run `luca state read`. The `pipelineStep` must be `plan-review` (entering execute) or `execute` (already advanced).
+2. If currently `plan-review`, run `luca state advance --to-step execute`.
+3. Run `luca phase current` to get the active slug.
+
+## Read the plan
+
+Read `.luca/phases/<slug>/plan.md`. If the plan doesn't exist or appears empty, abort and direct the user back to `/phase-plan`.
+
+## Delegate to the executor subagent
+
+Spawn the `luca-executor` subagent via the `Agent` tool with a prompt that includes:
+- The full plan content
+- The phase slug
+- Whatever constraints apply (e.g. test-driven development, no commits without verification)
+
+The subagent does the actual code-writing work. **You are orchestration only** — do not start editing files yourself in this skill. Code writes happen inside the subagent's tool calls, which the stage-gate hook allows because we're in `EXECUTING` phase.
+
+## Verification gate
+
+When the executor returns, run `luca state advance --to-step checks` to enter the mechanical verification step (typecheck + tests).
+
+The checks step is its own skill; `/phase-execute` is done once the executor reports completion.
+
+## What you must NOT do
+
+- Do NOT advance to `checks` until the executor reports that the plan is implemented.
+- Do NOT skip writing the execute summary — the executor produces one and writes it with the `Write` tool to `<dir>/execute/summary.md` (the canonical path); the hook blocks any other `.luca/` write.
+- Do NOT commit on behalf of the user during execute. Commits are FINALIZING-only and the hook blocks them here.