@alecsibilia/luca 13.0.0-alpha.1

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

@@ -0,0 +1,256 @@
+---
+name: quick
+description: Execute a quick ad-hoc task with Luca quality guarantees but minimal ceremony.
+---
+
+<main>
+# Luca Quick
+
+Execute small, ad-hoc tasks with Luca guarantees (atomic commits, workflow-state tracking) while skipping optional agents (research, plan-reviewer, verifier).
+
+Quick mode is the same system with a shorter path:
+
+- Invokes the architect mode-agent (planning) + the `executor` subagent
+- Skips researcher, plan-reviewer, verifier
+- Quick tasks live in a phase directory like any other phase (per LUCA_DIR_CONTRACT)
+- Tracked via the canonical workflow state machine
+
+**Use when:** You know exactly what to do and the task is small enough to not need research or verification.
+
+## Sub-agent Delegation Requirements
+
+This skill is an **orchestrator**. YOU MUST delegate work to subagents using the Task tool.
+
+**Required subagents for this skill:**
+
+- The `architect` mode-agent performs the planning work in v13 (the v12-era `lu-planner` subagent was dropped per plan §5.6)
+- `executor` - Executes the plan
+
+**DO NOT** attempt to plan or execute yourself. Spawn the appropriate subagents via the `Task` tool, or invoke the architect mode-agent.
+
+## Process
+
+### Step 0: Resolve Model Profile
+
+```bash
+MODEL_PROFILE=$(cat .luca/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Models are resolved at runtime via `resolveModelForAgent(agentName, complexity)` from the centralized routing table — the orchestrator does not pick model strings.
+
+### Step 1: Pre-flight Validation
+
+Check that an active Luca project exists:
+
+```bash
+# Auto-initialize the canonical .luca/ skeleton if missing (quick mode works without a full roadmap)
+if [ ! -d .luca ]; then
+  luca init 2>/dev/null || true
+fi
+```
+
+Quick tasks work independently — no `roadmap.md` required. The `luca init` command writes the canonical `.luca/` skeleton per LUCA_DIR_CONTRACT.
+
+### Step 2: Get Task Description
+
+Use AskQuestion tool:
+
+- header: "Quick Task"
+- question: "What do you want to do?"
+
+Store response as `$DESCRIPTION`.
+
+Generate slug from description:
+
+```bash
+slug=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
+```
+
+### Step 3: Calculate Next Quick Task Number
+
+```bash
+mkdir -p .luca/quick
+last=$(ls -1d .luca/quick/[0-9][0-9][0-9]-* 2>/dev/null | sort -r | head -1 | xargs -I{} basename {} | grep -oE '^[0-9]+')
+
+if [ -z "$last" ]; then
+  next_num="001"
+else
+  next_num=$(printf "%03d" $((10#$last + 1)))
+fi
+```
+
+### Step 4: Create Quick Task Directory
+
+```bash
+QUICK_DIR=".luca/quick/${next_num}-${slug}"
+mkdir -p "$QUICK_DIR"
+```
+
+### Step 5: Spawn Planner (Quick Mode)
+
+**MANDATORY**: Invoke the architect mode-agent (which performs planning in v13 — the v12-era `lu-planner` subagent was dropped per plan §5.6). Do NOT attempt to plan yourself.
+
+First, read context:
+
+```bash
+# Read workflow state from .luca/state.json via the luca CLI
+STATE_JSON=$(luca state read 2>/dev/null || echo '{"initialized":false}')
+# Recall session context from MuninnDB:
+# mcp__muninn__muninn_recall(vault: "default", context: "current session context for quick task")
+WORKING_CONTENT="[recalled from MuninnDB session context]"
+```
+
+Then spawn the architect mode-agent:
+
+```python
+Task(
+  prompt="""
+<planning_context>
+
+**Mode:** quick
+**Task:** {description}
+**Quick Task Number:** {next_num}
+**Quick Task Directory:** {quick_dir}
+
+**Project State:**
+{state_content}
+
+**Working Memory:**
+{working_content}
+
+</planning_context>
+
+<quick_mode_constraints>
+- Create a SINGLE plan with 1-3 focused tasks
+- Target ~30% context usage (simple, focused)
+- No research or verification needed
+- Tasks should be directly actionable
+</quick_mode_constraints>
+
+<output_requirements>
+- Create plan.md in {quick_dir} (canonical filename per LUCA_DIR_CONTRACT)
+- Plan should have clear tasks with verification criteria
+- Return summary of plan created
+</output_requirements>
+
+Create a quick plan for this task.
+""",
+  subagent_type="architect",
+  description="Quick plan: {description}"
+)
+```
+
+**Do NOT proceed until the Task returns.**
+
+### Step 6: Spawn Executor
+
+**MANDATORY**: You MUST spawn a lu-executor sub-agent. Do NOT attempt to execute yourself.
+
+First, read the plan:
+
+```bash
+PLAN_CONTENT=$(cat "${QUICK_DIR}/plan.md")
+# Read workflow state from .luca/state.json via the luca CLI
+STATE_JSON=$(luca state read 2>/dev/null || echo '{"initialized":false}')
+```
+
+Then spawn the executor:
+
+```python
+Task(
+  prompt="""
+<execution_context>
+
+**Mode:** quick
+**Quick Task Number:** {next_num}
+**Quick Task Directory:** {quick_dir}
+
+**Plan:**
+{plan_content}
+
+**Project State:**
+{state_content}
+
+</execution_context>
+
+<execution_rules>
+- Execute all tasks in the plan
+- Commit each task atomically
+- Do NOT update `.luca/roadmap.md` (quick tasks are separate phases per the contract)
+- Write the execution summary to the canonical `execute/summary.md`
+</execution_rules>
+
+<output_requirements>
+- Create `execute/summary.md` in `{quick_dir}` (canonical per LUCA_DIR_CONTRACT)
+- Return commit hash and summary of what was done
+</output_requirements>
+
+Execute this quick task plan.
+""",
+  subagent_type="executor",
+  description="Execute quick: {description}"
+)
+```
+
+**Do NOT proceed until the Task returns.**
+
+### Step 7: Advance Workflow State
+
+Advance the pipeline through learn/complete via the standard transitions:
+
+```bash
+luca state advance --to-step learn
+luca state advance --to-step complete
+```
+
+### Step 8: Final Commit and Completion
+
+```bash
+git add .
+bun run commit --message="${DESCRIPTION}" --type=docs --scope=quick-${next_num} --no-push --skip-checks
+```
+
+Display completion:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Luca ► QUICK TASK COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Quick Task ${next_num}: ${DESCRIPTION}
+
+Summary: ${QUICK_DIR}/execute/summary.md
+Commit: ${commit_hash}
+
+Ready for next task: /quick
+```
+
+## Success Criteria
+
+- [ ] `.luca/` directory exists (auto-created via `luca init` if needed)
+- [ ] `.luca/state.json` exists (auto-created via `luca init` if needed)
+- [ ] User provides task description
+- [ ] Slug generated (lowercase, hyphens, max 40 chars)
+- [ ] Next phase number calculated (zero-padded NN per LUCA_DIR_CONTRACT)
+- [ ] Phase directory created at `.luca/phases/NN-slug/`
+- [ ] `plan.md` written by the architect mode-agent
+- [ ] `execute/summary.md` written by the `executor` subagent
+- [ ] Workflow state advanced through learn/complete steps
+- [ ] Artifacts committed
+
+## Next Steps
+
+| Condition | Action | Command |
+|-----------|--------|---------|
+| Task complete | Check project status | `/progress` |
+| More quick tasks | Run another | `/quick` |
+| Want to commit | Commit changes | Run `bun run commit` |
+| Want PR | Create pull request | Run `gh pr create` |
+
+**Primary:** `/progress` — See project status after quick task
+
+**Also available:**
+
+- `/quick` — Run another quick task
+- `/help` — See all available commands
+</main>

package/dist/claude/skills/rename-audit/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: rename-audit
+description: "Find stale references across the repo after renaming a file, pipeline step, export, symbol, ticket ID, or convention. Searches .md/.ts/.tsx/.mjs/.json/.jsonl, plus .claude/, .luca/, and .changeset/ artifacts. Read-only audit — never edits files. Use when the user says \"rename audit\", \"audit renames\", \"find stale refs\", \"post-rename check\", or invokes /rename-audit."
+---
+
+# Skill: rename-audit
+
+Read-only audit for stale references after a rename. Surfaces every file that still mentions the old name so the caller can decide whether to edit or leave it (e.g. historical changesets are typically left alone).
+
+## Step 1 — Parse arguments
+
+Required: `oldName` (the string being phased out), `newName` (its replacement).
+Optional: `scope` (`step` | `file` | `export` | `symbol` | `ticket` | `convention`) to refine the search. Optional: `extraExtensions` (e.g. `['.yaml']`) to widen scope.
+
+If args are missing, prompt the user once with `AskUserQuestion`. Reject if `oldName === newName`.
+
+## Step 2 — Enumerate source files
+
+Use `git ls-files` to enumerate tracked files (honors `.gitignore`).
+Default extensions: `.md`, `.ts`, `.tsx`, `.mjs`, `.json`, `.jsonl`.
+Default include dirs (in addition to tracked source): `.claude/`, `.luca/`, `.changeset/`.
+
+## Step 3 — Grep for the old name
+
+Run the `Grep` tool (or `rg`) for the `oldName` substring across the enumerated files. Use a case-sensitive match by default; offer case-insensitive on `scope: 'convention'`. Collect every `file:line:snippet` hit.
+
+## Step 4 — Classify hits
+
+Bucket each hit by file type:
+
+- **code** — `*.ts` / `*.tsx` / `*.mjs` in `src/`, `packages/`
+- **test** — `*.test.ts` / `*.spec.ts`
+- **docs** — `*.md` outside `.luca/`
+- **state** — `.luca/`, `.changeset/`
+- **config** — `*.json`, `*.jsonl`, `tsconfig.json`, `package.json`, `bunfig.toml`
+
+For each bucket, decide an advisory action:
+
+- `code` / `test` → MUST-FIX (compile/test regression risk)
+- `docs` / `config` → SHOULD-FIX (drift over time)
+- `state` → ADVISORY (historical artifacts may legitimately keep the old name)
+
+## Step 5 — Report
+
+Emit a markdown table grouped by bucket. For each row: `<file>:<line> <snippet (≤80 chars)>`. End with a summary line:
+`Total: N matches across M files; K MUST-FIX, L SHOULD-FIX, P advisory.`
+
+If `0 matches`, report `✅ No stale references found.`
+
+## Constraints
+
+This is a **READ-ONLY audit**. Never call `Write`, `Edit`, `NotebookEdit`, or any other file-mutating tool. Use `Bash` only for read-only discovery (`git ls-files`, `rg`) — never for mutation. Never auto-fix. Surface the findings so the caller can decide; the caller may then invoke `/gh-pr-address` or hand-edit.

package/dist/claude/skills/repo-audit/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: repo-audit
+description: Run repo structure audit to detect naming violations, orphaned files, and convention drift. Supports quick and full audit modes.
+---
+
+<main>
+# Repo Audit
+
+Run a repo structure health check to detect naming violations, orphaned files, import boundary violations, and convention drift.
+
+**Arguments:** `[--quick|--full] [--fix]`
+
+## Sub-agent Delegation
+
+This skill delegates the analysis to the `lu-repo-architect` agent:
+
+```
+Task(
+  agent: "lu-repo-architect",
+  prompt: "Run {mode} repo audit on this codebase. Report findings in structured format."
+)
+```
+
+## Instructions
+
+### 1. Determine Audit Mode
+
+- `--quick` or TRIVIAL/SIMPLE complexity: Quick audit (naming, boundaries, drift only)
+- `--full` or COMPLEX/CRITICAL complexity: Full audit (all checks including circular imports, dead exports)
+- Default (MODERATE): Standard audit
+
+Read complexity from the canonical workflow state:
+```bash
+COMPLEXITY=$(luca state read 2>/dev/null | jq -r '.complexity // "MODERATE"')
+```
+
+### 2. Run Automated Checks
+
+Run existing validation scripts first (these provide baseline data):
+
+```bash
+# Domain boundary check
+bun run scripts/check-domain-boundaries.ts 2>&1
+
+# Build drift check
+bun run check:drift 2>&1
+```
+
+### 3. Delegate to lu-repo-architect
+
+Spawn the agent for deeper analysis based on the mode:
+
+```
+Task(
+  agent: "lu-repo-architect",
+  prompt: "Run {AUDIT_MODE} repo audit. The automated checks returned: {SCRIPT_RESULTS}. Now perform the additional checks for this mode and produce a structured health report."
+)
+```
+
+### 4. Display Results
+
+Present the health report from the agent. Format:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ REPO HEALTH REPORT -- {mode} audit
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overall: {PASS|WARN|FAIL} ({score}/100)
+
+{structured findings table}
+
+{issues list with severity}
+```
+
+### 5. Auto-Fix Mode (--fix)
+
+If `--fix` is passed and issues are auto-fixable (naming, empty dirs):
+- Rename files to kebab-case
+- Remove empty directories
+- Report what was fixed
+
+## Notes
+
+- This skill is invoked as `/repo-audit` or automatically at phase boundaries
+- The lu-repo-architect agent performs the actual analysis
+- Existing scripts (check-domain-boundaries, check-drift) handle the mechanical checks
+</main>

package/dist/claude/skills/repo-cleanup/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: repo-cleanup
+description: Scan the repository for AI-session debris and optionally clean it up.
+---
+
+# /repo-cleanup
+
+Scan the repository for AI-session debris — orphaned scripts, misplaced source files, tool artifacts, dead exports, `.luca/` contract violations, repo-root markdown debris — and optionally apply the remediations.
+
+The scan is performed by the **`luca-shadow-scanner`** subagent (strictly read-only). This command drives that scan and applies fixes through the **`luca repo cleanup-apply`** CLI (the destructive write half).
+
+## Parse arguments
+
+Parse `$ARGUMENTS` for flags:
+
+- `--quick` — quick scan (categories 1 + 3 only)
+- `--full` — full scan (all 7 categories, including dead exports)
+- `--dry-run` — show findings without applying anything
+- `--fix` — auto-apply every `auto_fixable` finding without prompting
+- `--category=N` — restrict to a single detection category (1–7)
+
+If no scan-mode flag is given, default to **`standard`** mode with interactive review.
+
+Resolve `<repo_vault>` from `.luca/config.json` → `muninn.vault`, falling back to `"default"`.
+
+## Step 1 — Scan
+
+Spawn the **`luca-shadow-scanner`** subagent via the `Agent` tool. The task prompt must include:
+
+- The scan mode (`quick` | `standard` | `full`) resolved from the flags.
+- Any `--category=N` filter — tell the scanner to report only that category.
+
+The subagent ends its response with a single JSON block conforming to `ShadowScanReportSchema` (`scan_mode`, `categories_scanned`, `findings[]`, `summary`, `scanned_at`).
+
+## Step 2 — Parse the report
+
+Take the **last JSON block** of the subagent's response as the `ShadowScanReport`. Each entry in `findings[]` has: `category`, `severity`, `file_path`, `description`, `recommendation`, `recommended_action` (`delete` | `move` | `gitignore`), `target_path?`, `auto_fixable`.
+
+Display the findings banner: total count plus the per-severity breakdown from `summary`.
+
+## Step 3 — Handle the findings
+
+- **No findings** (`summary.total === 0`) → report a clean scan and stop.
+
+- **`--dry-run`** → display all findings grouped by severity (critical first) and stop. Apply nothing.
+
+- **`--fix`** → for every finding where `auto_fixable === true`, stage that single finding object in a JSON file and run:
+
+  ```
+  # /tmp/luca-cleanup-finding.json holds the single finding object
+  luca repo cleanup-apply --file /tmp/luca-cleanup-finding.json --confirm
+  ```
+
+  Findings with `auto_fixable === false` (e.g. repo-root markdown, SUMMARY moves) are listed for the user but not auto-applied.
+
+- **Interactive mode** (default) → present each finding sorted by severity (critical first). For each one, offer three choices:
+
+  - **Fix** → stage the single finding object in a JSON file and run `luca repo cleanup-apply --file <path> --confirm`. For a `move`, the finding must carry `target_path`; if it does not, ask the user where it should go and add `target_path` to the file before running.
+  - **Keep** → record the user's decision so the file is not re-flagged next scan:
+
+    First call `mcp__muninn__muninn_remember` with `vault: "<repo_vault>"`, `concept: "shadow-debt:kept:<file_path>"`, and content noting the user approved keeping `<file_path>` with an ISO timestamp. Then promote it: `mcp__muninn__muninn_trust({ id: <returned id>, trust: "verified", vault: "<repo_vault>" })` — this is a user-confirmed decision. The `luca-shadow-scanner` recalls `shadow-debt:kept` entries and excludes them from future scans.
+  - **Skip** → take no action; the file will be flagged again on the next scan.
+
+## Step 4 — Store the cleanup metric
+
+After processing every finding, record what the cleanup did (`metric:*` routes to the repo vault per the vault-routing rule):
+
+```
+mcp__muninn__muninn_remember({
+  vault: "<repo_vault>",
+  concept: "metric:shadow-debt-cleanup-<ISO timestamp>",
+  content: JSON.stringify({
+    scan_mode, total, fixed, kept, skipped, cleaned_at
+  })
+})
+```
+
+The `luca-shadow-scanner` already stores the raw scan counts under `metric:shadow-debt-scan-*`; this metric captures the action outcome (`fixed` / `kept` / `skipped`).
+
+$ARGUMENTS