oh-my-customcode 0.80.0 → 0.82.0

package/templates/.claude/skills/wiki/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: wiki
+description: Generate and maintain a persistent codebase wiki — LLM-built interlinked markdown knowledge base (Karpathy LLM Wiki pattern)
+scope: core
+version: 1.0.0
+user-invocable: true
+argument-hint: "[ingest|query|lint] [args...]"
+effort: high
+---
+
+<!-- Inspired by Andrej Karpathy's "LLM Wiki" pattern:
+     https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
+     Core idea: the LLM incrementally builds and maintains a persistent wiki of
+     interlinked markdown files — a compounding artifact that grows richer over time. -->
+
+# Wiki Skill
+
+Builds and maintains a persistent, interlinked markdown wiki for the project codebase. Each run is incremental — only pages whose sources changed are rewritten. Over time the wiki becomes the fastest path to codebase understanding for both humans and LLMs.
+
+## Usage
+
+```
+/omcustom:wiki                          # Full wiki generation / incremental update
+/omcustom:wiki ingest <path>            # Ingest a specific file or directory
+/omcustom:wiki ingest .claude/agents/  # Ingest all agent definitions
+/omcustom:wiki query <question>         # Query the wiki with natural language
+/omcustom:wiki lint                     # Health check — orphans, broken refs, stale pages
+```
+
+## Wiki Directory Structure
+
+The wiki lives at `wiki/` in the project root (git-tracked). Create on first run if absent.
+
+```
+wiki/
+├── index.yaml                 # Structured content catalog — YAML for machine-parseable page index
+├── log.duckdb                 # Append-only operation log — DuckDB for SQL-queryable analytics
+├── architecture/              # Architecture & design pages
+├── agents/                    # Agent documentation pages
+├── skills/                    # Skill documentation pages
+├── rules/                     # Rule analysis pages
+├── guides/                    # Guide summary pages
+├── workflows/                 # Workflow & process pages
+└── concepts/                  # Cross-cutting concept pages
+```
+
+## Operations
+
+### Default — Full Wiki Generation / Incremental Update
+
+Invoked with `/omcustom:wiki` (no arguments).
+
+**Step 1 — Scan codebase structure**
+
+Read the following sources:
+- `.claude/agents/*.md` — all agent definitions
+- `.claude/skills/*/SKILL.md` — all skill definitions
+- `.claude/rules/*.md` — all rule files
+- `guides/*/` — all guide directories (read README or first `.md` found)
+- `CLAUDE.md` — project overview
+
+**Step 2 — Determine what needs updating (incremental mode)**
+
+For each source file: compare its modification date against the `updated` field of the corresponding wiki page frontmatter (if the page exists). Only regenerate pages where the source is newer than the wiki page, or the wiki page does not yet exist.
+
+On first run, generate all pages.
+
+**Step 3 — Generate wiki pages (parallel, per R009)**
+
+Split work by category across parallel subagents (max 4 concurrent per R009):
+
+| Batch | Categories |
+|-------|------------|
+| Batch 1 | agents/, skills/ |
+| Batch 2 | rules/, guides/ |
+| Batch 3 | architecture/, workflows/, concepts/ |
+
+Each subagent:
+1. Reads its assigned source files
+2. Creates or updates wiki pages following the Wiki Page Format below
+3. Writes pages to the correct subdirectory
+
+**Step 4 — Update index.yaml**
+
+After all page batches complete, regenerate `index.yaml` with current page list.
+
+**Step 5 — Insert into log.duckdb**
+
+```
+## [YYYY-MM-DD HH:MM] full_update | Full wiki update
+- Pages created: N
+- Pages updated: M
+- Sources scanned: K
+```
+
+**Step 6 — Display summary**
+
+```
+[wiki] Full update complete
+├── Created: N new pages
+├── Updated: M pages
+├── Unchanged: K pages
+└── Index: wiki/index.yaml
+```
+
+---
+
+### `ingest <path>` — Targeted Ingest
+
+Ingest one or more specific files or a directory. Useful after adding a new agent or skill.
+
+**Step 1** — Read the specified path(s). If a directory, read all `.md` files within.
+
+**Step 2** — For each source file, determine which wiki pages it should affect:
+- Direct page: the primary page for that entity
+- Cross-reference pages: pages that link to or depend on this entity
+
+A single source file typically affects 5–15 wiki pages (primary + all pages that reference it).
+
+**Step 3** — Update affected wiki pages: rewrite cross-reference sections in related pages, update the primary page with new content.
+
+**Step 4** — Update `index.yaml` if new pages were created.
+
+**Step 5** — Insert into `log.duckdb`:
+
+```
+## [YYYY-MM-DD HH:MM] ingest | <path>
+- Source: <path>
+- Pages created: N
+- Pages updated: M
+- Cross-references updated: K
+```
+
+---
+
+### `query <question>` — Wiki Query
+
+Answer a natural language question using wiki content as the knowledge base.
+
+**Step 1** — Read and parse `wiki/index.yaml` to identify the 3–7 most relevant pages for the question.
+
+**Step 2** — Read those pages in parallel (R009).
+
+**Step 3** — Synthesize a direct answer. Cite specific wiki pages inline: `[wiki/agents/mgr-creator.md]`.
+
+**Step 4** — If the synthesized answer itself is a valuable insight not captured in any existing page, offer: `"This synthesis could be saved as a new wiki page. Save it? [Y/n]"`
+
+If yes, delegate to the subagent to create the page in `wiki/concepts/`.
+
+**Step 5** — Insert into `log.duckdb`:
+
+```
+## [YYYY-MM-DD HH:MM] query | <question>
+- Pages consulted: N
+- New concept page created: yes/no
+```
+
+---
+
+### `lint` — Wiki Health Check
+
+**Step 1 — Collect inventory**
+
+- All wiki pages: glob `wiki/**/*.md` (exclude index.yaml, log.duckdb)
+- All links within wiki pages: extract `[[...]]` wikilinks and `[text](path)` markdown links
+- All source files: scan `.claude/agents/`, `.claude/skills/`, `.claude/rules/`, `guides/`
+
+**Step 2 — Run checks**
+
+| Check | How to Detect |
+|-------|---------------|
+| Orphan pages | Wiki pages with zero inbound links from other wiki pages |
+| Broken cross-references | `[[page-name]]` or `(path)` link targets that don't exist in `wiki/` |
+| Stale pages | Source file modification date newer than page's `updated` frontmatter field |
+| Missing pages | Source entities that exist in codebase but have no corresponding wiki page |
+| Contradictions | Pages that make conflicting claims about the same entity (heuristic: search for conflicting status/count statements) |
+
+**Step 3 — Report findings**
+
+```
+[wiki lint] Health check results
+├── Orphan pages (N): wiki/agents/old-agent.md, ...
+├── Broken refs (N): wiki/skills/foo.md → [[missing-page]]
+├── Stale pages (N): wiki/rules/r007.md (source updated 2026-04-10, wiki 2026-03-15)
+├── Missing pages (N): .claude/agents/new-agent.md has no wiki page
+└── Contradictions (N): wiki/architecture/overview.md vs wiki/concepts/orchestration.md
+```
+
+**Step 4 — Suggest fixes**
+
+For each category: suggest the command to fix (e.g., `/omcustom:wiki ingest .claude/agents/new-agent.md`).
+
+**Step 5 — Insert into log.duckdb**
+
+```
+## [YYYY-MM-DD HH:MM] lint | Health check
+- Orphans: N | Broken refs: M | Stale: K | Missing: J | Contradictions: L
+- Status: HEALTHY / NEEDS ATTENTION
+```
+
+---
+
+## Wiki Page Format
+
+Every wiki page follows this template exactly:
+
+```markdown
+---
+title: Page Title
+type: architecture|agent|skill|rule|guide|workflow|concept
+updated: YYYY-MM-DD
+sources:
+  - path/to/source1.md
+  - path/to/source2.md
+related:
+  - [[related-page-1]]
+  - [[related-page-2]]
+---
+
+# Page Title
+
+Brief description (1-2 sentences).
+
+## Overview
+
+Main content — purpose, key capabilities, design intent.
+
+## Key Details
+
+Specifics: configuration, fields, options, constraints.
+
+## Relationships
+
+- **Depends on**: [[page-a]], [[page-b]]
+- **Used by**: [[page-c]]
+- **See also**: [[page-d]]
+
+## Sources
+
+- `path/to/source.md` — what was extracted from this source
+```
+
+### Wikilink Style
+
+Use BOTH formats for cross-references so the wiki is readable in Obsidian and in standard markdown viewers:
+
+- Wikilinks (Obsidian-compatible): `[[page-name]]`
+- Standard markdown links: `[Page Name](../category/page-name.md)`
+
+Example: `[[mgr-creator]]` and `[mgr-creator](../agents/mgr-creator.md)`
+
+---
+
+## index.yaml Format
+
+```yaml
+# wiki/index.yaml — Machine-parseable wiki page index
+# Updated by /omcustom:wiki after every operation
+
+meta:
+  updated: "2026-04-12"
+  total_pages: 231
+  total_sources: 203
+
+pages:
+  architecture:
+    - file: architecture/overview.md
+      title: System Architecture Overview
+      summary: Three-layer structure and compilation metaphor
+    - file: architecture/orchestration.md
+      title: Orchestration
+      summary: Main conversation as sole orchestrator with routing skills
+
+  agents:
+    - file: agents/lang-golang-expert.md
+      title: Go Language Expert
+      summary: Expert Go developer for idiomatic, performant Go code
+    # ... one entry per agent
+
+  skills:
+    - file: skills/wiki.md
+      title: Wiki Skill
+      summary: Generate and maintain persistent codebase wiki
+    # ... one entry per skill
+
+  rules:
+    - file: rules/r000.md
+      title: "R000: Language & Delegation Policy"
+      summary: Korean I/O, English files, delegation model
+    # ... one entry per rule
+
+  guides:
+    - file: guides/golang.md
+      title: Go Guide
+      summary: Reference documentation for Go development
+    # ... one entry per guide
+
+  workflows:
+    - file: workflows/development-workflow.md
+      title: Development Workflow
+      summary: Intent detection to implementation pipeline
+
+  concepts:
+    - file: concepts/compilation-metaphor.md
+      title: Compilation Metaphor
+      summary: Core design philosophy mapping software compilation to agent system
+```
+
+Advantages over markdown index:
+- Machine-parseable: LLMs and scripts can filter by category, search by title
+- Structured: each entry has file, title, summary as discrete fields
+- Queryable: `yq '.pages.agents[] | select(.title | contains("Go"))'`
+
+---
+
+## log.duckdb Format
+
+The wiki log uses DuckDB — a single-file analytical database for SQL-queryable operation history.
+
+### Schema
+
+```sql
+CREATE TABLE IF NOT EXISTS wiki_log (
+  id INTEGER PRIMARY KEY,
+  timestamp TIMESTAMP DEFAULT current_timestamp,
+  operation VARCHAR NOT NULL,     -- 'full_update' | 'ingest' | 'query' | 'lint'
+  target VARCHAR,                 -- file path or question text
+  pages_created INTEGER DEFAULT 0,
+  pages_updated INTEGER DEFAULT 0,
+  pages_consulted INTEGER DEFAULT 0,
+  coverage VARCHAR,               -- 'full' | 'partial' | 'miss' (for queries)
+  details JSON                    -- flexible metadata
+);
+```
+
+### Writing entries
+
+```bash
+duckdb wiki/log.duckdb "INSERT INTO wiki_log (operation, target, pages_created, pages_updated, details) VALUES ('full_update', 'all', 231, 0, '{\"sources_scanned\": 203}');"
+```
+
+### Querying
+
+```bash
+# Recent operations
+duckdb wiki/log.duckdb "SELECT timestamp, operation, target, pages_created FROM wiki_log ORDER BY timestamp DESC LIMIT 10;"
+
+# Query coverage stats
+duckdb wiki/log.duckdb "SELECT coverage, COUNT(*) FROM wiki_log WHERE operation='query' GROUP BY coverage;"
+
+# Operations per day
+duckdb wiki/log.duckdb "SELECT DATE_TRUNC('day', timestamp) as day, COUNT(*) FROM wiki_log GROUP BY day ORDER BY day;"
+```
+
+### Fallback
+
+If `duckdb` CLI is not installed, fall back to appending JSON lines to `wiki/log.jsonl`:
+```json
+{"timestamp":"2026-04-12T10:00:00","operation":"full_update","target":"all","pages_created":231,"pages_updated":0,"details":{"sources_scanned":203}}
+```
+
+Install DuckDB: `brew install duckdb` (macOS) or `pip install duckdb`
+
+---
+
+## Execution Rules
+
+| Rule | Requirement |
+|------|-------------|
+| R000 | Wiki page content in English; user communication in Korean |
+| R009 | Parallel agents for independent category batches (max 4 concurrent) |
+| R010 | Orchestrator delegates ALL wiki file writes to subagents |
+| R006 | Only SKILL.md is created by this skill; wiki pages are runtime artifacts |
+| Git tracking | `wiki/` directory is git-tracked (not in .gitignore) |
+| Incremental | On re-runs, skip pages whose sources haven't changed |
+| First run | Create `wiki/` directory structure before writing any pages |
+| log.duckdb | Always insert; never delete or rewrite existing log entries |
+
+### Parallel Execution Pattern (Full Update)
+
+```
+Orchestrator
+├── [1] subagent: agents/ category (reads .claude/agents/*.md, writes wiki/agents/*.md)
+├── [2] subagent: skills/ category (reads .claude/skills/*/SKILL.md, writes wiki/skills/*.md)
+├── [3] subagent: rules/ category (reads .claude/rules/*.md, writes wiki/rules/*.md)
+└── [4] subagent: guides/ category (reads guides/*/, writes wiki/guides/*.md)
+  [wait for batch 1 to complete]
+├── [5] subagent: architecture/ + workflows/ + concepts/ (synthesizes from all sources)
+  [wait]
+└── [6] subagent: index.yaml + log.duckdb update
+```
+
+---
+
+## What Makes a Good Wiki Page
+
+A wiki page is NOT a file summary — it is a synthesized knowledge article. Good pages:
+
+- **Explain purpose and design intent**, not just what fields exist
+- **Show relationships** — what depends on this, what this depends on
+- **Highlight non-obvious constraints** — gotchas, ordering requirements, exceptions
+- **Cross-reference liberally** — 5–10 outbound links per page is healthy
+- **Stay concise** — aim for 150–300 words of body text; tables over prose where possible
+
+---
+
+## Tips
+
+- The wiki is just markdown — viewable in Obsidian, VS Code, GitHub, and any markdown renderer
+- `wiki/index.yaml` acts as the LLM's "search engine" at moderate scale — keep it accurate
+- Over time, the wiki becomes the fastest way to understand the codebase for new contributors and LLMs alike
+- Run `lint` regularly (after major structural changes) to keep the wiki healthy
+- When a query answer synthesizes something genuinely new, file it as a `concepts/` page — it compounds value
+- The `log.duckdb` provides an SQL-queryable audit trail of how the wiki evolved
+
+## Integration
+
+| Rule / Skill | Integration |
+|--------------|-------------|
+| R009 | Parallel agents for category batches; max 4 concurrent |
+| R010 | All wiki writes delegated to subagents; orchestrator reads only |
+| R000 | Wiki content in English; responses to user in Korean |
+| R013 | Ecomode auto-activates when 4+ parallel agents writing pages |
+| R015 | Display operation plan with page counts before execution |
+| result-aggregation | Aggregate per-batch page counts for final summary |
+| update-docs | Complement: update-docs syncs CLAUDE.md counts; wiki syncs knowledge content |

package/templates/.claude/skills/wiki-rag/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: wiki-rag
+description: Use the project wiki as RAG knowledge source — search wiki pages to answer codebase questions before exploring raw files
+scope: core
+version: 1.0.0
+user-invocable: true
+argument-hint: "<question>"
+effort: medium
+---
+
+# Wiki RAG Skill
+
+Query the project wiki to answer questions about the codebase. The wiki is a pre-compiled knowledge base — searching it is faster and more accurate than exploring raw source files.
+
+## Usage
+
+```
+/omcustom:wiki-rag "how does orchestration work?"
+/omcustom:wiki-rag "what agents handle database tasks?"
+/omcustom:wiki-rag "explain the compilation metaphor"
+```
+
+Also triggered automatically by intent-detection when a user asks about project architecture, agent roles, skill purposes, or rule behavior.
+
+## Workflow
+
+### Step 1: Load Index
+
+Read and parse `wiki/index.yaml` to get the full page catalog. If `wiki/index.yaml` does not exist, report:
+
+```
+[wiki-rag] Wiki not initialized. Run /omcustom:wiki first to create wiki/index.yaml.
+```
+
+Then abort.
+
+### Step 2: Identify Relevant Pages
+
+From the question and the index, identify 3–7 most relevant wiki pages. Selection criteria:
+
+| Criterion | Detail |
+|-----------|--------|
+| Title/summary keyword match | Direct term overlap with the question |
+| Category relevance | Architecture questions → `architecture/`; agent questions → `agents/` |
+| Cross-reference chains | Follow `[[related]]` links to surface adjacent context |
+
+### Step 3: Read Pages (Parallel)
+
+Read identified pages in parallel per R009. Extract sections relevant to the question; ignore unrelated sections to control context size (R013).
+
+### Step 4: Synthesize Answer
+
+Compose a direct answer citing wiki pages inline:
+
+```
+[wiki/architecture/orchestration.md] 참조 — 메인 대화가 유일한 오케스트레이터...
+```
+
+Answer format:
+
+- **Direct answer first** (2–3 sentences)
+- Supporting details from wiki pages
+- Inline citations to specific wiki pages (`[wiki/path/to/page.md]`)
+- "See also" links for further reading
+
+### Step 5: Evaluate Coverage
+
+After synthesizing, assess whether the wiki alone was sufficient.
+
+| Coverage Level | Condition | Action |
+|---------------|-----------|--------|
+| Full | Wiki pages answer the question completely | Return wiki-sourced answer |
+| Partial | Wiki covers some aspects; gaps remain | Supplement with raw codebase exploration (Read/Glob/Grep); offer to ingest |
+| Miss | Wiki has no relevant pages | Full raw exploration; offer to create wiki page |
+
+If raw file exploration was needed, offer to persist the new knowledge:
+
+```
+[wiki-rag] This answer required raw file exploration. Save findings to wiki? [Y/n]
+```
+
+If yes: delegate wiki page creation/update to the wiki-curator agent (R010 — orchestrator delegates all wiki writes).
+
+### Step 6: Log Query
+
+Insert into `wiki/log.duckdb`:
+
+```bash
+duckdb wiki/log.duckdb "INSERT INTO wiki_log (operation, target, pages_consulted, coverage, details) VALUES ('query', '{question}', N, 'full/partial/miss', '{\"fallback\": false, \"new_page_created\": false}');"
+```
+
+Log writes are delegated to a subagent (R010).
+
+## Integration with Intent Detection
+
+The following trigger patterns route user questions to wiki-rag automatically:
+
+| Trigger Keywords | Language | Confidence | Action |
+|-----------------|----------|------------|--------|
+| "어떻게 작동", "how does X work" | KO/EN | 85% | wiki-rag |
+| "무슨 에이전트", "which agent" | KO/EN | 80% | wiki-rag |
+| "규칙", "rule R0XX" | KO/EN | 75% | wiki-rag |
+| "아키텍처", "architecture" | KO/EN | 90% | wiki-rag |
+| "워크플로우", "workflow" | KO/EN | 85% | wiki-rag |
+
+Patterns should be registered in `.claude/skills/intent-detection/patterns/agent-triggers.yaml` when that file is updated.
+
+## Fallback Strategy
+
+| Wiki Coverage | Action |
+|--------------|--------|
+| Full (answer from wiki alone) | Return wiki-sourced answer |
+| Partial (wiki + raw files needed) | Supplement with raw exploration, offer to ingest findings |
+| Miss (wiki has nothing relevant) | Full raw exploration, offer to create new wiki page |
+
+For partial and miss cases: always acknowledge what the wiki covered before pivoting to raw exploration. Do not silently fall back.
+
+## Execution Rules
+
+| Rule | Requirement |
+|------|-------------|
+| R000 | Answers to user in Korean; wiki content and citations reference English file paths |
+| R009 | Parallel reads for identified wiki pages (Step 3) |
+| R010 | All wiki write operations (log.duckdb, new pages) delegated to subagents |
+| R013 | Ecomode: return concise answers when context pressure is high; suppress "See also" section |
+
+## What Makes a Good Wiki-RAG Answer
+
+- **Cites specific wiki pages** — not vague "the wiki says..." but `[wiki/agents/mgr-creator.md]`
+- **Provides actionable information** — tells the user what to do, not just what exists
+- **Links to related pages** for readers who want to go deeper
+- **Acknowledges gaps honestly** — never hallucinate content not found in the wiki
+- **Offers to improve wiki coverage** when gaps are found — compounding the knowledge base over time
+
+## Integration with /omcustom:wiki
+
+| Skill | Role |
+|-------|------|
+| `wiki` | Builds and maintains the wiki (ingest, update, lint) |
+| `wiki-rag` | Queries the wiki as a RAG source; surfaces gaps; triggers ingest offers |
+
+wiki-rag is the read-path; wiki is the write-path. They share `wiki/index.yaml` and `wiki/log.duckdb` as the coordination layer.
+
+## Integration
+
+| Rule / Skill | Integration |
+|--------------|-------------|
+| R009 | Parallel page reads in Step 3 |
+| R010 | Log writes and wiki page creation delegated to subagents |
+| R000 | Korean user responses; English wiki content and paths |
+| R013 | Ecomode: suppress extended "See also" section; summary answer only |
+| R015 | Intent detection routes architecture/agent/rule questions here at 75–90% confidence |
+| wiki | Counterpart write-path skill; wiki-rag triggers ingest offers to wiki when gaps found |
+| intent-detection | Registers trigger patterns for auto-routing user questions to wiki-rag |