@alecsibilia/luca 13.0.0-alpha.1

package/dist/claude/skills/seed-memory/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: seed-memory
+description: Seed MuninnDB with project knowledge from existing BRAIN.md, MEMORY.md, WORKING.md, and procedure files. Run once per project to populate MuninnDB with existing knowledge. Idempotent -- safe to run multiple times.
+---
+
+<main>
+# Seed Memory
+
+Migrate file-based project knowledge into MuninnDB as structured, queryable entities. This skill reads existing planning files and stores their content as engrams with proper entity naming, hierarchy, and deduplication.
+
+## When to Use
+
+- First time adopting MuninnDB on an existing project
+- After significant manual edits to BRAIN.md, MEMORY.md, or procedures
+- To refresh MuninnDB after a reset or data loss
+- Safe to re-run -- idempotent via entity existence checks
+
+## Vault
+
+Always use vault `"default"` for all MuninnDB operations.
+
+## Entity Naming Conventions
+
+All entities use type-prefixed names for consistent recall and traversal:
+
+| Source | Concept Prefix | Examples |
+|--------|---------------|----------|
+| BRAIN.md sections | `brain:` | `brain:project-identity`, `brain:stack`, `brain:conventions` |
+| MEMORY.md patterns | `pattern:` | `pattern:bun-runtime-requirement` |
+| MEMORY.md decisions | `decision:` | `decision:no-classes-architecture` |
+| MEMORY.md pitfalls | `pitfall:` | `pitfall:generated-files-direct-edit` |
+| MEMORY.md preferences | `preference:` | `preference:lodash-over-builtin` |
+| WORKING.md sections | `session:` | `session:findings`, `session:progress` |
+| Procedure files | `procedure:` | `procedure:deploy-checklist` |
+
+---
+
+## Procedure
+
+### Step 1: Detect existing files
+
+Check for the following files and directories in the project root. Report which exist and which are missing:
+
+```
+.luca/BRAIN.md
+.luca/MEMORY.md
+.luca/WORKING.md
+.luca/procedures/
+```
+
+Read each file that exists. If none exist, report "No planning files found -- nothing to seed" and stop.
+
+### Step 2: Seed BRAIN.md
+
+If `.luca/BRAIN.md` exists:
+
+1. Read the file content
+2. Parse the major sections (look for ## headings: Project Identity, Stack, Architecture, Conventions, Preferences, etc.)
+3. **Check for existing entity** using `mcp__muninn__muninn_find_by_entity`:
+   - vault: "default"
+   - entity_name: "brain:project-identity"
+4. **If entity exists**: Use `mcp__muninn__muninn_evolve` to update the root engram with the latest content
+5. **If entity does not exist**: Use `mcp__muninn__muninn_remember_tree` to store as a hierarchical tree:
+   - vault: "default"
+   - Root concept: "brain:project-identity"
+   - Root content: The full BRAIN.md content or a summary of the project identity
+   - Children: One child per major section, each with:
+     - concept: `brain:<section-slug>` (e.g., "brain:stack", "brain:conventions", "brain:architecture")
+     - content: The section content as natural language
+
+**Example tree structure:**
+
+```json
+{
+  "vault": "default",
+  "root": {
+    "concept": "brain:project-identity",
+    "content": "Luca Framework -- agentic development tooling monorepo. Builds agents, skills, rules, hooks for AI-assisted development.",
+    "type": "project_identity",
+    "summary": "Project identity and conventions for luca-framework",
+    "entities": [{"name": "luca-framework", "type": "project"}]
+  },
+  "children": [
+    {
+      "concept": "brain:stack",
+      "content": "TypeScript, Bun runtime, Zod schemas, functional patterns. No classes.",
+      "type": "project_stack",
+      "summary": "Technology stack for luca-framework"
+    },
+    {
+      "concept": "brain:conventions",
+      "content": "Kebab-case files, barrel-only index.ts, schema-first parsing...",
+      "type": "project_conventions",
+      "summary": "Code conventions for luca-framework"
+    }
+  ]
+}
+```
+
+### Step 3: Seed MEMORY.md
+
+If `.luca/MEMORY.md` exists:
+
+1. Read the file content
+2. Parse each entry by identifying sections and sub-sections. Look for patterns like:
+   - **Patterns** section entries (## or ### headings under a Patterns section)
+   - **Decisions** section entries
+   - **Pitfalls** section entries
+   - **Preferences** section entries
+   - Any other categorized knowledge sections
+3. For each entry found:
+   - **Check for existing entity** using `mcp__muninn__muninn_find_by_entity`:
+     - entity_name: The concept name (e.g., "pattern:bun-runtime-requirement")
+   - **If entity exists**: Use `mcp__muninn__muninn_evolve` to update with latest content
+   - **If entity does not exist**: Add to the batch for creation
+4. Store all new entries using `mcp__muninn__muninn_remember_batch`:
+   - vault: "default"
+   - Each memory includes:
+     - concept: `<type>:<slug>` (e.g., "pattern:bun-runtime-requirement", "pitfall:generated-files-direct-edit")
+     - content: The full entry text as natural language
+     - type: One of "pattern", "decision", "pitfall", "preference"
+     - summary: A one-line summary of the entry
+     - entities: Include `{"name": "luca-framework", "type": "project"}` and any other relevant entities
+
+**Concept naming rules:**
+
+- Slugify the entry title: lowercase, replace spaces with hyphens, remove special characters
+- Prefix with the section type: `pattern:`, `decision:`, `pitfall:`, `preference:`
+- Example: "Bun Runtime Requirement" under Pitfalls becomes `pitfall:bun-runtime-requirement`
+- Example: "Generated Files -- Never Edit Directly" under Patterns becomes `pattern:generated-files-never-edit-directly`
+
+### Step 4: Seed WORKING.md
+
+If `.luca/WORKING.md` exists and is not empty:
+
+1. Read the file content
+2. Parse the major sections (Findings, Progress, Blockers, Decisions, etc.)
+3. For each non-empty section:
+   - **Check for existing entity** using `mcp__muninn__muninn_find_by_entity`:
+     - entity_name: `session:<section-slug>`
+   - **If entity exists**: Use `mcp__muninn__muninn_evolve` to update
+   - **If entity does not exist**: Use `mcp__muninn__muninn_remember` to store:
+     - vault: "default"
+     - concept: `session:<section-slug>` (e.g., "session:findings", "session:progress")
+     - content: The section content
+     - type: "session_context"
+     - summary: One-line description of the section
+     - entities: Include session ID if available, project name
+
+**Note:** WORKING.md content is session-scoped and may be stale. Include a note in the content about when it was seeded.
+
+### Step 5: Seed Procedures
+
+If `.luca/procedures/` directory exists:
+
+1. List all `.md` files in the directory
+2. For each procedure file:
+   - Read the file content
+   - Extract the procedure name from the filename (strip .md, use as slug)
+   - **Check for existing entity** using `mcp__muninn__muninn_find_by_entity`:
+     - entity_name: `procedure:<procedure-slug>`
+   - **If entity exists**: Use `mcp__muninn__muninn_evolve` to update the root
+   - **If entity does not exist**: Use `mcp__muninn__muninn_remember_tree`:
+     - vault: "default"
+     - Root concept: `procedure:<procedure-slug>`
+     - Root content: Procedure overview or full content
+     - Children: One child per major step or section (if the procedure has clear steps)
+     - type: "procedure"
+     - summary: One-line description of the procedure
+
+### Step 6: Verify seeding
+
+After all seeding is complete:
+
+1. Use `mcp__muninn__muninn_recall` to verify key entities were stored:
+   - `muninn_recall(vault="default", context="brain project identity")`
+   - `muninn_recall(vault="default", context="patterns and pitfalls")`
+   - `muninn_recall(vault="default", context="procedures")` (if procedures were seeded)
+
+2. Report a summary:
+
+```
+Seed Memory Complete
+====================
+Files processed:
+  - BRAIN.md: {created|updated|skipped}
+  - MEMORY.md: {N} entries ({created} new, {updated} updated)
+  - WORKING.md: {created|updated|skipped|empty}
+  - Procedures: {N} files processed
+
+Entities created: {total_new}
+Entities updated: {total_updated}
+Entities skipped: {total_skipped}
+
+Verification:
+  - Brain recall: {pass|fail}
+  - Memory recall: {pass|fail}
+  - Procedure recall: {pass|fail|n/a}
+```
+
+---
+
+## Idempotency Guarantee
+
+This skill is safe to run multiple times because:
+
+1. **Before creating any entity**, it checks `mcp__muninn__muninn_find_by_entity` for an existing entity with the same name
+2. **If found**: Uses `mcp__muninn__muninn_evolve` to update the content (preserves entity ID, updates content)
+3. **If not found**: Creates the entity fresh
+4. **Entity names are deterministic**: Derived from file names and section headings, so the same input always produces the same entity names
+
+This means running the skill twice on the same files will update existing entities rather than creating duplicates.
+
+---
+
+## Error Handling
+
+- **MuninnDB unavailable**: Report the error clearly and stop. Do not fall back to file writes.
+- **File read failure**: Skip the file, report which file failed, continue with others.
+- **Batch too large**: If MEMORY.md has more than 50 entries, split into multiple `muninn_remember_batch` calls (max 50 per batch).
+- **Malformed content**: If a file cannot be parsed into sections, store the entire file as a single entity with concept `<type>:raw-content`.
+
+---
+
+## MuninnDB Tools Reference
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `mcp__muninn__muninn_remember_tree` | Store hierarchical content | BRAIN.md, Procedures |
+| `mcp__muninn__muninn_remember_batch` | Store multiple flat entries | MEMORY.md entries |
+| `mcp__muninn__muninn_remember` | Store single entry | WORKING.md sections |
+| `mcp__muninn__muninn_find_by_entity` | Check if entity exists | Idempotency check before every create |
+| `mcp__muninn__muninn_evolve` | Update existing entity | When entity already exists |
+| `mcp__muninn__muninn_recall` | Verify stored content | Final verification step |
+</main>

package/dist/claude/skills/session-pause/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: session-pause
+description: Create a context handoff snapshot when pausing work mid-phase for later resumption.
+---
+
+<main>
+# Luca Pause Work
+
+Create `.continue-here.md` handoff file to preserve complete work state across sessions.
+
+Enables seamless resumption in fresh session with full context restoration.
+
+## Process
+
+### Step 1: Detect Current Phase
+
+Read current phase from the canonical workflow state:
+
+```bash
+STATE_JSON=$(luca state read 2>/dev/null || echo '{"initialized":false}')
+PHASE=$(echo "$STATE_JSON" | jq -r '.currentPhase // empty')
+PHASE_SLUG=$(echo "$STATE_JSON" | jq -r '.currentPhaseSlug // empty')
+```
+
+### Step 2: Gather Context
+
+Collect complete state for handoff:
+
+1. **Current position**: Which phase, which plan, which task
+2. **Work completed**: What got done this session
+3. **Work remaining**: What's left in current plan/phase
+4. **Decisions made**: Key decisions and rationale
+5. **Blockers/issues**: Anything stuck
+6. **Mental context**: The approach, next steps, "vibe"
+7. **Files modified**: What's changed but not committed
+
+Ask user for clarifications if needed.
+
+### Step 3: Write Handoff
+
+Write to `.luca/phases/XX-name/.continue-here.md`:
+
+```markdown
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: [timestamp]
+---
+
+<current_state>
+[Where exactly are we? Immediate context]
+</current_state>
+
+<completed_work>
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done]
+  </completed_work>
+
+<remaining_work>
+
+- Task 3: [what's left]
+- Task 4: Not started
+- Task 5: Not started
+  </remaining_work>
+
+<decisions_made>
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+  </decisions_made>
+
+<blockers>
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, what were you thinking, the plan]
+</context>
+
+<next_action>
+Start with: [specific first action when resuming]
+</next_action>
+```
+
+### Step 4: Commit
+
+```bash
+git add .
+bun run commit --message="[phase-name] paused at task [X]/[Y]" --type=chore --scope=wip --no-push --skip-checks
+```
+
+### Step 5: Confirm
+
+```
+✓ Handoff created: .luca/phases/[XX-name]/.continue-here.md
+
+Current state:
+- Phase: [XX-name]
+- Task: [X] of [Y]
+- Status: [in_progress/blocked]
+- Committed as WIP
+
+To resume: /session-resume
+```
+
+## Success Criteria
+
+- [ ] .continue-here.md created in correct phase directory
+- [ ] All sections filled with specific content
+- [ ] Committed as WIP
+- [ ] User knows location and how to resume
+
+## Next Steps
+
+This skill creates a handoff for resuming later. No immediate action needed.
+
+**When returning:**
+- `/session-resume` — Restore context and continue
+
+**Common follow-ups:**
+- `/help` — Review commands before stepping away
+</main>

package/dist/claude/skills/session-plan/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: session-plan
+description: Plan the next coding session using WSJF prioritization of pending todos and roadmap items.
+---
+
+<main>
+# Luca Session Planner
+
+Plan the next AI coding session (or week) by analyzing pending todos, scoring them with WSJF, and scheduling an optimal session plan.
+
+**Arguments:** `[sessions]` (optional - defaults to 1 for single session, use >1 for weekly planning)
+
+## Process
+
+### Step 0: Cognitive Pre-Flight
+
+1. **Load context from MuninnDB:**
+   - Recall project identity: `mcp__muninn__muninn_recall_tree(vault: "default", id: "brain:project-identity")`
+   - Recall session context: `mcp__muninn__muninn_recall(vault: "default", context: "current session context")`
+   - Recall planning patterns: `mcp__muninn__muninn_recall(vault: "default", context: "planning patterns, estimates, and workflow decisions")`
+
+2. **Initialize session in MuninnDB:**
+   - Store session info: `mcp__muninn__muninn_remember(vault: "default", concept: "session:info", content: "workflow=session-plan, started=[timestamp]")`
+   - Note any recalled calibration data for effort estimates
+
+### Step 1: Parse Pending Todos
+
+1. **Read backlog:**
+   - Read pending todos via `luca todo list --status pending --format json`
+   - Each entry returns title, area, source, body, priority
+   - The backlog is MuninnDB-backed; `luca todo` is the canonical surface
+
+2. **Check for dependencies:**
+   - Scan body content for references to other todos
+   - Mark items as dependency_free=true if no unresolved prerequisites
+
+3. **Display backlog summary:**
+   - Show count of pending todos by area
+   - Note any items with dependencies
+
+### Step 2: Invoke PM Agent (lu-pm-planner)
+
+1. **Prepare context for PM agent:**
+   - Package TodoMetadata[] as structured input
+   - Include `.luca/roadmap.md` for priority context
+   - Include dependency graph
+   - Include any calibration entries for effort estimates (via MuninnDB: `mcp__muninn__muninn_recall(vault: "default", context: "effort estimates and calibration data")`)
+
+2. **Spawn lu-pm-planner sub-agent:**
+   - Agent infers WSJF inputs (BV, TC, RR) for each todo from context
+   - Agent maps complexity to effort points
+   - Agent computes WSJF scores and ranks items
+   - Agent applies Big Rock First + WSJF tail scheduling
+   - Agent assigns quality zones
+   - Agent returns ResultEnvelope containing SessionPlan
+
+3. **Receive and validate result:**
+   - Parse ResultEnvelope from agent output
+   - Validate SessionPlan schema
+   - Extract any issues or warnings
+
+### Step 3: Technical Review (Optional)
+
+If `config.workflow.planner_review` is enabled (default: skip for now):
+
+1. **Pass session plan to code-architect:**
+   - Review dependency ordering correctness
+   - Validate effort estimates against historical data
+   - Check for hidden blockers or missing prerequisites
+   - Suggest reordering if technically warranted
+
+2. **Incorporate review feedback:**
+   - Append review comments to session plan rationale
+   - Flag any items the reviewer flagged as risky
+
+### Step 4: Present Session Plan
+
+Display the session plan to the user:
+
+1. **Big Rock callout:**
+
+   ```
+   Big Rock: "{title}" (WSJF {score}, {complexity})
+   Scheduled in Peak Zone (0-30% context)
+   ```
+
+2. **Ordered task list with zones:**
+
+   ```
+   | # | Task | WSJF | Zone | Effort |
+   |---|------|------|------|--------|
+   | 1 | Big Rock task | 4.2 | peak | 5 |
+   | 2 | Next task | 3.5 | good | 3 |
+   | ... |
+   ```
+
+3. **Mermaid gantt chart** (from session plan)
+
+4. **Rationale summary** (from PM agent)
+
+5. **Deferred items** (not scheduled this session)
+
+### Step 5: Weekly Planning (if sessions > 1)
+
+If `{ARGUMENTS}` specifies more than 1 session:
+
+1. Run `distributeWeekly(scored_items, sessions_count)` for multi-session planning
+2. Display per-session breakdown with allocation percentages
+3. Show weekly allocation: 60% needle movers, 25% quick wins, 10% maintenance, 5% reserve
+4. Display deferred items that didn't fit in the weekly plan
+
+</main>

package/dist/claude/skills/session-resume/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: session-resume
+description: Resume work from a previous session with full cognitive context restoration.
+---
+
+<main>
+# Luca Resume Work
+
+Restore complete project context and resume work seamlessly from previous session.
+
+## Process
+
+Follow the resume-project workflow which handles:
+
+1. **Project existence verification**
+   - Check for `.luca/` directory
+   - Error if project not initialized
+
+2. **State loading via the `luca` CLI**
+
+   ```bash
+   # Read the comprehensive state from .luca/state.json
+   STATE_JSON=$(luca state read 2>/dev/null || echo '{"initialized":false}')
+
+   # Extract complexity and phase info from the state JSON
+   COMPLEXITY=$(echo "$STATE_JSON" | jq -r '.complexity // "MODERATE"')
+   PHASE=$(echo "$STATE_JSON" | jq -r '.currentPhase // empty')
+   PIPELINE_STEP=$(echo "$STATE_JSON" | jq -r '.pipelineStep // "triage"')
+   ```
+
+   If state not initialized, reconstruct from artifacts (research.md, context.md, plan.md, audits/ under the active phase directory).
+
+3. **Incomplete work detection**
+   - For the active phase under `.luca/phases/<currentPhaseSlug>/`: check for `plan.md` without matching `execute/summary.md` (mid-phase abandonment) and for partially-filled `audits/` (mid-review abandonment).
+
+4. **Visual status presentation**
+   - Show progress bar
+   - Summarize recent work
+   - Display current position
+
+5. **Context-aware option offering**
+   - Check the active phase's `context.md` before suggesting plan vs discuss
+   - Offer appropriate next actions
+
+6. **Routing to appropriate next command**
+   - Execute phase if plans exist
+   - Plan phase if not planned
+   - Discuss phase if no context
+
+7. **Session continuity updates**
+   - Session continuity is auto-tracked by the state machine in `.luca/state.json` (no separate snapshot step needed).
+
+## Success Criteria
+
+- [ ] Project context fully restored
+- [ ] Checkpoint file processed (if exists)
+- [ ] Incomplete work detected
+- [ ] Clear next steps presented
+- [ ] User knows what to do next
+
+## Next Steps
+
+| Condition | Action | Command |
+|-----------|--------|---------|
+| Resumed successfully | Continue work | `/phase-execute {phase}` |
+| Need to check status | Review progress | `/progress` |
+| Context unclear | Check what's next | `/progress` |
+
+**Primary:** `/progress` — See current state and smart routing
+
+**Also available:**
+
+- `/phase-execute {phase}` — Continue execution directly
+- `/help` — Review available commands
+</main>

package/dist/claude/skills/todo-add/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: todo-add
+description: Capture an idea or task as a todo for later without acting on it now.
+---
+
+<main>
+# Luca Add Todo
+
+Capture idea or task as todo from current conversation.
+
+**Arguments:** `[description]` (optional - infers from conversation if not provided)
+
+## Process
+
+1. **Extract context:**
+   - If description provided: use it
+   - If not: infer from recent conversation context
+
+2. **Infer area:**
+   - Check file paths mentioned in conversation
+   - Categorize: api, ui, auth, data, etc.
+
+3. **Check for duplicates:**
+   - Search existing pending todos for similar content
+   - Warn if duplicate found
+
+4. **Persist the todo via the canonical CLI surface:**
+
+   \`\`\`bash
+   luca todo add --title "<title>" --area "<area>" --priority "<low|medium|high|critical>" --source "<origin>" --body "<source context>"
+   \`\`\`
+
+   Backlog state lives in MuninnDB (`todo:*` engrams under the repo vault) — there is no `.luca/todos/` directory in the LUCA_DIR_CONTRACT.
+
+5. **Confirm:**
+
+   ```
+   ✓ Todo captured: {title}
+
+   Area: {area}
+   Backlog: MuninnDB todo:<id> (see `luca todo list`)
+
+   /todo-check to review pending
+   ```
+
+## Todo File Format
+
+```markdown
+---
+title: {title}
+area: {api/ui/auth/data/etc}
+created: {timestamp}
+source: conversation
+---
+
+## Context
+
+{What the user was discussing when this came up}
+
+## Task
+
+{Specific thing to do}
+
+## Notes
+
+{Any additional context}
+```
+
+## Success Criteria
+
+- [ ] Todo content extracted (from args or conversation)
+- [ ] Area inferred from context
+- [ ] Duplicate check performed
+- [ ] Todo engram persisted to MuninnDB backlog (`todo:*` in repo vault)
+- [ ] Todo persisted to MuninnDB backlog via `luca todo add` (read back via `luca todo list` to confirm)
+- [ ] User knows how to review todos
+
+## Next Steps
+
+**Primary:** Continue current work — todo captured for later
+
+**Also available:**
+- `/todo-check` — Review all pending todos
+- `/progress` — Check project status
+</main>