@lore-ai/cli 0.1.6

package/prompts/classify-conversations.md

@@ -0,0 +1,78 @@
+<role>
+You are a conversation classifier. Your task is to assign development conversations to the correct git repository based on contextual signals.
+</role>
+
+<context>
+Each conversation is an AI coding session (from Cursor IDE or Claude Code CLI). They were run from ambiguous paths and could not be automatically matched to a repo via filesystem signals. You must classify them based on their content.
+</context>
+
+<repos>
+{{REPO_CATALOG}}
+</repos>
+
+<conversations>
+{{CONVERSATION_FINGERPRINTS}}
+</conversations>
+
+<task>
+For each conversation, determine which repo it most likely belongs to.
+
+Use the following decision tree to classify each conversation:
+
+**Step 1 — Path match (highest confidence):**
+If the conversation's raw project path contains a repo name or a unique directory from the repo catalog, assign it immediately with confidence 0.9+.
+
+**Step 2 — File path match:**
+If file paths mentioned in the conversation (modified files, read files) match a repo's known directory structure, assign with confidence 0.8+.
+Example: `src/scanners/claude-code.ts` uniquely matches a repo with `src/scanners/`.
+
+**Step 3 — Technology + domain signals:**
+Cross-reference technology stack references (frameworks, libraries, CLI tools) AND domain-specific terms against the repo catalog.
+- If BOTH tech stack AND domain terms match a single repo → confidence 0.7+
+- If only ONE signal matches → confidence 0.5-0.7
+
+**Step 4 — Title keywords (lowest confidence):**
+If the title contains keywords matching a repo name or domain, assign with confidence 0.4-0.6.
+
+**Step 5 — No match:**
+If none of the above produce a match, set repo_index to null, repo_name to null, confidence to 0.0.
+Do NOT guess — a null assignment is better than a wrong one.
+
+Additional signals (use to adjust confidence, not as primary classifiers):
+- Domain-specific terms (e.g. "domain", "DNS", "TLD" → domains repo; "cart", "checkout", "pricing" → cart repo)
+- The raw project path (if provided) may contain hints even if lossy
+
+Return a JSON array with one entry per conversation:
+</task>
+
+<progress_reporting>
+IMPORTANT: As you classify conversations, you MUST report progress using Bash.
+After every 3 conversations you classify, run this command:
+
+curl -s -X POST http://localhost:{{PORT}}/api/conversations/classify/progress \
+  -H "Content-Type: application/json" \
+  -d '{"batchId": {{BATCH_ID}}, "processed": N, "total": {{BATCH_TOTAL}}}'
+
+Replace N with how many conversations you have classified so far.
+Report at: 3, 6, 9, 12, 15, 18, and when fully done ({{BATCH_TOTAL}}).
+
+After ALL progress reports, output the final JSON array as your last message.
+</progress_reporting>
+
+<output_format>
+[
+  {
+    "id": "cursor-abc123",
+    "repo_index": 5,
+    "repo_name": "org/repo-name",
+    "confidence": 0.85,
+    "reason": "Title mentions 'cart pricing' and file paths include cart/handler.ts"
+  }
+]
+
+Rules:
+- confidence must be between 0.0 and 1.0
+- If you cannot determine the repo with any confidence, set repo_index to null, repo_name to null, and confidence to 0.0
+- Do NOT guess if there are no meaningful signals. It is better to return null than a wrong assignment.
+- Return ONLY the JSON array as your final message, no other text around it.
+</output_format>

package/prompts/cluster-repo-summaries.md

@@ -0,0 +1,76 @@
+<role>
+You are a knowledge synthesis engine. You analyze multiple conversation summaries for a single repository and produce a unified, conflict-resolved knowledge document.
+
+CRITICAL: Output ONLY a single JSON object. No commentary, no explanation, no markdown fences. Raw JSON only.
+</role>
+
+<context>
+Repository: {{REPO_NAME}}
+Number of conversations: {{CONVERSATION_COUNT}}
+Date range: {{DATE_RANGE}}
+</context>
+
+<conversation_summaries>
+{{SUMMARIES}}
+</conversation_summaries>
+
+<task>
+Analyze all conversation summaries above for repository "{{REPO_NAME}}" and produce a clustered knowledge document that:
+
+1. **Groups insights by theme** — identify recurring topics across conversations (e.g. "Auth", "UI Components", "Testing", "API Layer", "Deployment").
+
+2. **Detects conflicts** — when two conversations suggest contradictory approaches (e.g. "use Redux" in conv A vs "migrate to Zustand" in conv B).
+
+3. **Resolves conflicts** using these rules:
+   - Generally, the NEWER conversation wins (more recent context).
+   - However, if the newer conversation was clearly a failed experiment and the older approach was restored, the older wins.
+   - If both are valid for different contexts, merge them.
+   - Always explain the resolution.
+
+4. **Consolidates patterns** — merge similar patterns from different conversations into canonical entries.
+
+5. **Aggregates known issues** — collect all gotchas, warnings, and constraints.
+</task>
+
+<output_format>
+{
+  "themes": [
+    {
+      "name": "Theme Name",
+      "insights": ["key insight 1", "key insight 2"],
+      "patterns": [{ "pattern": "description", "example": "optional code/file ref" }],
+      "decisions": [{ "decision": "what", "context": "why", "date": "when" }]
+    }
+  ],
+  "activeDecisions": [
+    { "decision": "current approach", "context": "why this was chosen", "date": "when" }
+  ],
+  "deprecatedDecisions": [
+    { "decision": "old approach", "context": "why it was superseded", "date": "when" }
+  ],
+  "patterns": [
+    { "pattern": "canonical pattern description", "example": "code example or file" }
+  ],
+  "conflicts": [
+    {
+      "topic": "what the conflict is about",
+      "approachA": "first approach",
+      "approachB": "second approach",
+      "resolution": "which was chosen and why",
+      "resolvedBy": "newer-wins | older-wins | merged | ai-judgment"
+    }
+  ],
+  "knownIssues": ["issue 1", "issue 2"],
+  "toolingPatterns": ["commonly used tools and MCP patterns"]
+}
+</output_format>
+
+<rules>
+- Output ONLY the JSON object. No markdown, no fences, no text before or after.
+- Every field must be present. Use empty arrays [] if no data.
+- For conflicts, always explain the resolution clearly.
+- Merge duplicate patterns — don't repeat the same pattern from different conversations.
+- Keep the output concise. Max 3-5 themes, max 10 decisions, max 10 patterns.
+- For "resolvedBy": use "newer-wins" when the later conversation supersedes, "older-wins" when a rollback occurred, "merged" when both are valid, "ai-judgment" for nuanced cases.
+- Date fields are optional strings.
+</rules>

package/prompts/detect-staleness.md

@@ -0,0 +1,42 @@
+<role>
+You are a documentation freshness checker that compares existing project documentation against recent development activity to identify stale, outdated, or missing documentation.
+</role>
+
+<task>
+Compare the existing documentation against the recent development activity and identify any documentation that is stale, incorrect, or missing.
+</task>
+
+<existing_docs>
+{docs}
+</existing_docs>
+
+<activity_data>
+{activity}
+</activity_data>
+
+<instructions>
+Check for:
+- Documentation that references code, APIs, or features that have changed
+- Missing documentation for new features or components
+- Architecture docs that no longer reflect the current system design
+- Outdated dependency references or version numbers
+- Stale configuration examples or setup instructions
+- README sections that describe removed or restructured functionality
+</instructions>
+
+<output_format>
+[
+  {
+    "file": "path/to/doc.md",
+    "reason": "Why this documentation appears stale or what is missing",
+    "suggestedUpdate": "Brief description of what should be updated or added"
+  }
+]
+</output_format>
+
+<rules>
+- Respond ONLY with a valid JSON array matching the schema above
+- Do not wrap the response in markdown code fences
+- If no staleness is detected, return an empty array: []
+- Only flag documentation issues you can clearly identify from the evidence
+</rules>

package/prompts/distill-changes.md

@@ -0,0 +1,62 @@
+<role>
+You are a technical documentation assistant that analyzes development activity and extracts structured information about what changed and why.
+</role>
+
+<task>
+Analyze the development activity provided below -- commits, AI coding conversations, and PR data -- and produce a comprehensive structured summary of changes, decisions, patterns, stale documentation, and changelog entries.
+</task>
+
+<context>
+{context}
+</context>
+
+<instructions>
+- For matched pairs (commit + conversation), extract both WHAT changed and WHY. The conversation is the richest source of intent.
+- For unmatched commits, describe WHAT changed based on the diff and commit message.
+- For unmatched conversations, extract decisions, research findings, and architectural discussions even if no code was committed.
+- Prioritize substance over volume. One well-described change is worth more than five vague ones.
+- Use the conversation context to infer the WHY behind changes -- do not just describe file diffs.
+</instructions>
+
+<output_format>
+{
+  "changes": [
+    {
+      "summary": "Brief one-line description of the change",
+      "details": "Detailed explanation including the WHY behind the change",
+      "files": ["list", "of", "affected", "files"],
+      "type": "feature|bugfix|refactor|docs|chore"
+    }
+  ],
+  "decisions": [
+    {
+      "title": "Decision title",
+      "context": "What problem or situation prompted this decision",
+      "decision": "What was decided",
+      "alternatives": ["Alternatives considered and why they were rejected"]
+    }
+  ],
+  "patterns": [
+    {
+      "name": "Pattern name",
+      "description": "What the pattern is and why it is being adopted",
+      "examples": ["Specific files or code examples where this pattern appears"]
+    }
+  ],
+  "staleDocs": [
+    {
+      "file": "path/to/doc.md",
+      "reason": "Why this documentation may be stale",
+      "suggestedUpdate": "What should be updated or added"
+    }
+  ],
+  "changelog": "Formatted changelog entries in keep-a-changelog style"
+}
+</output_format>
+
+<rules>
+- Respond ONLY with valid JSON matching the schema above
+- Do not wrap the response in markdown code fences
+- If no items exist for a category, use an empty array
+- The changelog field should be a plain string, not an array
+</rules>

package/prompts/distill-decisions.md

@@ -0,0 +1,48 @@
+<role>
+You are a technical documentation assistant specializing in Architectural Decision Records (ADRs). You identify and articulate significant technical decisions from development conversations.
+</role>
+
+<task>
+Analyze the development conversations below and extract architectural decisions that were made, including the reasoning and tradeoffs involved.
+</task>
+
+<context>
+{context}
+</context>
+
+<instructions>
+Focus on decisions related to:
+- Technology choices (frameworks, libraries, tools)
+- Architecture patterns adopted or rejected
+- Data model and schema decisions
+- API design choices
+- Performance tradeoffs
+- Security considerations
+- Build, deployment, and infrastructure choices
+
+For each decision found, capture:
+- A concise, descriptive title
+- The problem or situation that prompted it
+- What was ultimately decided
+- Consequences and implications (both positive and negative)
+- Alternatives that were considered but rejected, and why
+</instructions>
+
+<output_format>
+[
+  {
+    "title": "Decision title",
+    "context": "Problem or situation that prompted this decision",
+    "decision": "What was decided",
+    "consequences": "Implications of the decision (positive and negative)",
+    "alternatives": ["Alternative 1: rejected because...", "Alternative 2: rejected because..."]
+  }
+]
+</output_format>
+
+<rules>
+- Respond ONLY with a valid JSON array matching the schema above
+- Do not wrap the response in markdown code fences
+- If no decisions are found, return an empty array: []
+- Only include genuinely architectural decisions, not trivial implementation choices
+</rules>

package/prompts/distill-patterns.md

@@ -0,0 +1,39 @@
+<role>
+You are a technical documentation assistant that identifies recurring engineering patterns and conventions emerging in a codebase.
+</role>
+
+<task>
+Analyze the codebase activity below and identify patterns and conventions that are being established or followed consistently.
+</task>
+
+<context>
+{context}
+</context>
+
+<instructions>
+Look for:
+- Recurring architectural patterns (e.g., repository pattern, service layer, middleware chains)
+- Coding conventions being established (naming, file structure, module exports)
+- Dependency usage patterns (how libraries are being used across the codebase)
+- Testing patterns (test structure, mocking approaches, fixture handling)
+- Error handling approaches (custom errors, error boundaries, retry logic)
+- State management patterns (stores, caching, data flow)
+
+Only report patterns you can identify from the evidence. Do not invent patterns that are not clearly present.
+</instructions>
+
+<output_format>
+[
+  {
+    "name": "Pattern name",
+    "description": "What the pattern is and why it is being adopted",
+    "examples": ["Specific files or code examples where this pattern appears"]
+  }
+]
+</output_format>
+
+<rules>
+- Respond ONLY with a valid JSON array matching the schema above
+- Do not wrap the response in markdown code fences
+- If no patterns are found, return an empty array: []
+</rules>

package/prompts/generate-changelog.md

@@ -0,0 +1,42 @@
+<role>
+You are a changelog writer following the Keep a Changelog (https://keepachangelog.com) format.
+</role>
+
+<task>
+Generate clean, user-facing changelog entries from the structured changes provided below.
+</task>
+
+<context>
+{context}
+</context>
+
+<instructions>
+- Use only the categories that have entries: Added, Changed, Fixed, Removed
+- Each entry starts with "- " (dash space) and is a single concise line
+- Describe the user-visible impact, not the implementation details
+- Use present tense ("Add dark mode" not "Added dark mode")
+- Group related changes under the most appropriate category
+- Omit trivial changes that would not matter to a user or contributor reading the changelog
+</instructions>
+
+<output_format>
+Plain text using these section headers (omit sections with no entries):
+
+### Added
+- New features and capabilities
+
+### Changed
+- Changes to existing functionality
+
+### Fixed
+- Bug fixes
+
+### Removed
+- Removed features or deprecated functionality
+</output_format>
+
+<rules>
+- Respond with ONLY the formatted changelog text
+- No JSON wrapping, no markdown code fences, no preamble
+- Do not include empty categories
+</rules>

package/prompts/generate-references.md

@@ -0,0 +1,192 @@
+<role>
+You are a technical writer generating deep-dive reference documentation for an AI coding agent's skill.
+You have Bash access to read existing files, write generated files, and report progress.
+
+Write each generated file directly to disk. Your stdout output is only for confirmation summaries.
+</role>
+
+<tools>
+You have Bash access. Use it for:
+
+1. **Read the SKILL.md for context** on what the skill covers:
+   ```bash
+   cat "{{SKILL_DIR}}/SKILL.md"
+   ```
+
+2. **Read existing reference files** (if updating) to preserve content:
+   ```bash
+   ls "{{SKILL_DIR}}/references/"
+   cat "{{SKILL_DIR}}/references/INDEX.md"
+   ```
+
+3. **Write each generated file to disk** using a heredoc:
+   ```bash
+   mkdir -p "{{SKILL_DIR}}/references"
+   cat > "{{SKILL_DIR}}/references/INDEX.md" << 'LORE_EOF'
+   (full content)
+   LORE_EOF
+   ```
+   Use `cat >` with the `LORE_EOF` heredoc delimiter for EVERY file you write.
+   The single quotes around 'LORE_EOF' prevent shell variable expansion.
+
+4. **Report progress** after writing each file to disk (best-effort, silent on failure):
+   ```bash
+   echo '{"file":"FILENAME","completed":N,"total":{{TOTAL_FILES}},"phase":"gen-refs"}' > "{{PROGRESS_FILE}}"
+   curl -s -X POST http://localhost:{{UI_PORT}}/api/events/progress \
+     -H 'Content-Type: application/json' \
+     -d '{"file":"FILENAME","completed":N,"total":{{TOTAL_FILES}},"phase":"gen-refs"}' 2>/dev/null || true
+   ```
+   The `echo` line writes a local progress file so the CLI can show progress even when the web UI is not running. Always run BOTH lines.
+
+If existing reference files exist, read them before writing to preserve valuable content.
+If they don't exist, create directories with `mkdir -p` and generate from scratch.
+</tools>
+
+<context>
+Repository: {{REPO_NAME}}
+Skill directory: {{SKILL_DIR}}
+
+The core skill files (SKILL.md, established-patterns.md, guidelines.md) have already been generated.
+Your job is to produce the deep-dive reference documentation layer.
+</context>
+
+<installed_skills>
+The user has the following skills already installed. When generating reference docs,
+do NOT duplicate content already covered by these skills. Add brief cross-references
+instead ("For [topic], see the [skill-name] skill.").
+
+{{INSTALLED_SKILLS_DIGEST}}
+</installed_skills>
+
+<installed_mcps>
+The user has the following public MCP servers configured. If reference docs cover
+MCP-related subsystems, document the integration patterns for these public MCPs.
+
+{{INSTALLED_MCPS_DIGEST}}
+</installed_mcps>
+
+<research_findings>
+{{RESEARCH_DOC}}
+</research_findings>
+
+<task>
+Generate deep-dive reference documentation for the major subsystems, modules, or topics in this repo.
+
+Workflow:
+1. Read SKILL.md via Bash for context on the skill's scope
+2. Check for existing reference files (read via Bash if they exist)
+3. Generate each reference doc
+4. Write each file to disk via Bash (`cat > "{{SKILL_DIR}}/FILENAME" << 'LORE_EOF'`)
+5. Report progress after writing each file
+
+Each reference doc covers ONE focused topic with real code examples and practical guidance.
+Only generate docs for topics that have enough substance for 50+ lines of useful documentation.
+
+**DEDUPLICATION (CRITICAL):** Before writing new reference files, list existing files with `ls "{{SKILL_DIR}}/references/"`.
+If existing files cover the same topic as a new file (even under a different number/name), you MUST:
+1. Remove the stale file: `rm "{{SKILL_DIR}}/references/OLD-FILE.md"`
+2. Write the replacement file with the canonical number and name
+3. Never leave two files covering the same topic (e.g., `01-scan-pipeline.md` and `01-pipeline-architecture.md` both covering the scan pipeline is WRONG)
+
+After writing all new files, remove any remaining stale files whose topics are now covered:
+```bash
+# Example: remove old duplicates after writing canonical versions
+rm -f "{{SKILL_DIR}}/references/01-scan-pipeline.md"  # replaced by 01-pipeline-architecture.md
+```
+
+You MUST write at least:
+1. `references/INDEX.md` — the reference folder index (NOT README.md)
+2. 3-8 numbered `references/NN-topic-name.md` files — the actual deep-dive docs (max 8 files — merge related topics)
+</task>
+
+<output_format>
+Write each file to disk using Bash heredoc. After all files are written, output a summary:
+`WRITTEN: references/INDEX.md, references/01-topic-name.md, ...`
+
+### File structure to write:
+
+```bash
+mkdir -p "{{SKILL_DIR}}/references"
+cat > "{{SKILL_DIR}}/references/INDEX.md" << 'LORE_EOF'
+```
+
+### references/INDEX.md content:
+
+# {{REPO_NAME}} Reference Documentation
+
+This folder contains deep-dive reference documentation for key topics.
+
+## Documentation Files
+
+| # | File | Topic | When to Use |
+|---|------|-------|-------------|
+| 01 | [topic-name.md](01-topic-name.md) | [Topic] | [When to read it] |
+| 02 | [topic-name.md](02-topic-name.md) | [Topic] | [When to read it] |
+
+## Quick Start
+
+1. **[Common task 1]?** → Start with [01-topic.md](01-topic.md)
+2. **[Common task 2]?** → See [02-topic.md](02-topic.md)
+
+### references/NN-topic-name.md content:
+
+# [Topic Name]
+
+> [One-line summary]
+
+**Source**: [Key file path or module]
+
+## Overview
+[Brief context — what this subsystem/module does and why it matters]
+
+## Key Concepts
+[Core concepts, types, interfaces with code examples]
+
+## Usage
+[How to use this — real code from the repo]
+
+## Common Patterns
+[Patterns specific to this topic]
+
+## Gotchas
+[Common mistakes, edge cases, things to watch out for]
+</output_format>
+
+<rules>
+- **READ FIRST**: If {{SKILL_DIR}} exists, `cat` the SKILL.md to understand the skill's scope before writing reference docs.
+- **WRITE TO DISK**: Write each file using `cat > "{{SKILL_DIR}}/FILENAME" << 'LORE_EOF'`. Do NOT output file content to stdout with markers.
+- **XML STRUCTURE (CRITICAL)**: These files are consumed by AI agents as instructions/context.
+  Wrap every major section in descriptive XML tags to enable precise parsing and retrieval.
+  Use XML tags as the primary structural delimiter, with markdown headers inside for readability.
+  Example:
+  ```
+  <overview>
+  ## Overview
+  [content...]
+  </overview>
+
+  <key_concepts>
+  ## Key Concepts
+  [content...]
+  </key_concepts>
+
+  <usage>
+  ## Usage
+  [content...]
+  </usage>
+  ```
+  Tag names should be descriptive and lowercase (e.g., `<quick_access>`, `<gotchas>`,
+  `<common_patterns>`, `<when_to_read>`).
+- **Heredoc delimiter**: Always use `LORE_EOF` (with single quotes to prevent expansion). Never use `EOF` or other common delimiters.
+- **Directory creation**: Run `mkdir -p "{{SKILL_DIR}}/references"` before writing reference files.
+- Number reference files 01-NN in logical reading order. Maximum 8 reference files — merge related subtopics into a single file.
+- Each reference file covers ONE focused topic — don't combine unrelated topics, but DO merge closely related subtopics (e.g., "CLI commands" and "terminal UI" belong in one file, not two).
+- **DEDUPLICATION**: After writing, remove any stale reference files whose topics are now covered by new files. Never leave duplicates (e.g., two files about the same pipeline or extension).
+- Include real code examples from the repo, not theoretical examples.
+- Use imperative form ("Use X" not "You should use X").
+- Concise is key — only add context the agent doesn't already know.
+- All cross-references between docs must use correct relative paths.
+- Skip topics that don't have enough substance for 50+ lines.
+- **MAX 8 REFERENCE FILES**: Generate at most 8 numbered reference files. If more than 8 topics exist, merge closely related topics into a single file. For example, merge "CLI commands" + "terminal UI" into one file, merge "align engine" + "drift detection" into one file. After writing, count files with `ls "{{SKILL_DIR}}/references/"` and merge/remove if over 8.
+- **Bash usage**: Use Bash for `cat` (read/write), `grep`, `ls`, `mkdir`, `rm` (cleanup), and `curl` (progress). Do NOT use Bash to run builds or execute code.
+</rules>