palskills 1.0.9 → 1.0.11

package/bin/palskills.js

@@ -255,7 +255,14 @@ function generate(agent) {
 
 function skillContent(agent, skill) {
   const skills = {
-    elphidran: `# Elphidran — Design System Recommender
+    elphidran: `---
+name: elphidran
+description: "Design system recommender — analyzes project and generates .palbox/design.md with tokens, typography, spacing, and component patterns."
+version: 1.0.0
+license: MIT
+---
+
+# Elphidran — Design System Recommender
 **Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
 
 ## Role
@@ -294,13 +301,27 @@ Analyze the project and generate a complete design system specification.
 - Include implementation notes for Anubis
 - One design.md per project
 `,
-    lyleen: `# Lyleen — Palbox Knowledge Graph
-**Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
+    lyleen: `---
+name: lyleen
+description: "Palbox knowledge graph reader, bootstrapper & discoverer — creates .palbox/ if missing, traverses [[wikilinks]] for context, and auto-saves source code analysis to flows/."
+version: 4.0.0
+license: MIT
+---
+
+# Lyleen — Palbox Knowledge Graph
 
 ## Role
-Read and bootstrap the project knowledge graph (.palbox/).
+Read, bootstrap, and discover the project knowledge graph (.palbox/).
+
+## 3 Modes
 
-## If .palbox/ does NOT exist — BOOTSTRAP:
+| Mode | When | Action |
+|------|------|--------|
+| **BOOTSTRAP** | .palbox/ missing | Create full palbox from scratch |
+| **TRAVERSE** | "what do we know about X" | Read palbox entries → return context (read-only) |
+| **DISCOVER** | "learn/pelajari/study X" | Read source code → write flows/X.md + update architecture |
+
+## BOOTSTRAP (.palbox/ missing)
 1. Scan project: read package.json/requirements.txt/go.mod, list dirs, check git log, find tests
 2. Create .palbox/README.md — project name, tech stack, goals, [[links]]
 3. Create .palbox/architecture.md — folder tree, design patterns, key modules
@@ -308,13 +329,43 @@ Read and bootstrap the project knowledge graph (.palbox/).
 5. Create .palbox/flows/, .palbox/history/, .palbox/plans/
 6. Report: "Palbox bootstrapped. N files. Detected: [stack]."
 
-## If .palbox/ EXISTS — RETRIEVE:
+## TRAVERSE (read-only)
 1. Read README.md, architecture.md, methods.md
 2. Search flows/ and history/ for user keywords
 3. Extract [[wikilinks]], follow 1-2 hops
 4. Return context subgraph: seeds → 1-hop → 2-hop → conventions
-`,
-    jetdragon: `# Jetdragon — Planner
+
+## DISCOVER (auto-save to flows/)
+
+### When to use
+User says: "learn X", "pelajari Y", "discover Z", "analyze W", "study V"
+
+### Process
+1. **Identify target** — extract module/topic from user prompt
+2. **Find source files** — grep for keywords in .py/.ts/.js/.go/.rs files
+3. **Deep analysis** — for each file: entry points, data flow, dependencies, patterns, edge cases
+4. **Write flow doc** → .palbox/flows/<module>.md:
+   - Entry Points table (route/fn/class, type, source, description)
+   - Data Flow description
+   - Dependencies (internal + external + packages)
+   - Key Patterns detected
+   - Edge Cases & Error Handling
+   - Related: [[architecture]], [[methods]], [[history/]]
+5. **Update architecture.md** — if new module, append link
+6. **Report** — "Saved: flows/<module>.md, Files analyzed: N, Graph: +1 node +N edges"
+
+### Delimiter
+- DISCOVER → writes .palbox/flows/* (Lyleen's domain)
+- Panthalus → writes .palbox/history/* (development sessions)
+- NEVER cross domains`,
+    jetdragon: `---
+name: jetdragon
+description: "Planning specialist — asks clarifying questions, generates detailed plans with [[wikilinks]] to palbox context."
+version: 1.0.0
+license: MIT
+---
+
+# Jetdragon — Planner
 **Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
 
 ## Role
@@ -332,7 +383,14 @@ Create detailed implementation plans. Ask questions until clear.
 - Architecture notes, SOLID focus, Risks & Mitigations
 - All references use [[wikilinks]] to .palbox/ entries
 `,
-    anubis: `# Anubis — Developer
+    anubis: `---
+name: anubis
+description: "Development execution engine — executes approved plans via Codex CLI with SOLID + SRP + Ponytail. English only."
+version: 2.1.0
+license: MIT
+---
+
+# Anubis — Developer
 **Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
 
 ## Role
@@ -374,7 +432,14 @@ Ponytail rules:
 - Read existing files before modifying
 - Write tests if project has testing patterns
 - Non-trivial logic leaves one runnable check behind`,
-    panthalus: `# Panthalus — Archivist
+    panthalus: `---
+name: panthalus
+description: "Knowledge graph archivist — records sessions with bi-directional [[wikilinks]], creating traversable development history."
+version: 1.0.0
+license: MIT
+---
+
+# Panthalus — Archivist
 **Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
 
 ## Role
@@ -393,7 +458,14 @@ Record sessions to .palbox/ with bi-directional [[wikilinks]].
 - Key Decisions table, Lessons Learned (pitfalls, discoveries)
 - Backlinks section
 `,
-    astralym: `# Astralym — Orchestrator
+    astralym: `---
+name: astralym
+description: "State machine orchestrator — routes prompts through CHECK_GRAPH → DESIGN → PLANNING → DEVELOPING → RECORDING pipeline with state.md tracking."
+version: 1.0.0
+license: MIT
+---
+
+# Astralym — Orchestrator
 **Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
 
 ## Role

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palskills",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "AI-powered development pipeline — 5 Hermes Agent skills orchestrated as a knowledge graph",
   "keywords": [
     "hermes-agent",

package/skills/lyleen/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lyleen
-description: "Palbox knowledge graph reader & bootstrapper — creates .palbox/ if missing, then traverses [[wikilinks]] to retrieve connected context like an Obsidian vault."
-version: 3.0.0
+description: "Palbox knowledge graph reader, bootstrapper & discoverer — creates .palbox/ if missing, traverses [[wikilinks]] for context, and auto-saves source code analysis to flows/."
+version: 4.0.0
 author: Palskills
 license: MIT
 platforms: [linux, macos, windows]
@@ -39,6 +39,8 @@ Lyleen is the **gatekeeper** of the palskills knowledge graph. The palbox is an
 
 **Nodes** = `.md` files. **Edges** = `[[wikilinks]]` between them.
 
+> See `references/knowledge-graph-design.md` for the full design rationale behind the palbox graph architecture.
+
 ## How It Works
 
 ### Step 1: Check if Palbox Exists
@@ -152,7 +154,7 @@ Created `.palbox/` with interconnected nodes:
 Graph has [N] nodes and [M] edges.
 ```
 
-### Step 2b: Palbox Exists → TRAVERSE
+### Step 2b: Palbox Exists → TRAVERSE (Read-only)
 
 **Phase 1: Seed Discovery**
 
@@ -176,7 +178,7 @@ queue = seed_nodes
 for node in queue:
     visited.add(node)
     content = read(".palbox/" + node)
-    links = extract_wikilinks(content)  # regex: \[\[([^\]]+)\]\] 
+    links = extract_wikilinks(content)  # regex: \[\[([^\]]+)\]\]
     for link in links:
         resolved = resolve_link(link)  # handle paths, .md extension
         if resolved not in visited:
@@ -212,6 +214,101 @@ Matched: "login", "authentication"
 
 Return the subgraph to Astralym/Jetdragon. The context is now **relational** — not just a flat list of files, but a connected graph of knowledge.
 
+### Step 2c: Palbox Exists → DISCOVER (Auto-save to flows/)
+
+Triggered when the user explicitly asks to **learn**, **study**, **pelajari**, or **discover** a module, component, or flow. Unlike TRAVERSE (read-only), DISCOVER reads actual source code and **writes findings to `.palbox/flows/<module>.md`**.
+
+**When to use DISCOVER vs TRAVERSE:**
+
+| User says | Mode | Action |
+|-----------|------|--------|
+| "what do we know about auth" | TRAVERSE | Read palbox, return context |
+| "pelajari flow dan codebase export" | DISCOVER | Read source, write flow doc |
+| "learn the payment module" | DISCOVER | Read source, write flow doc |
+| "analyze how logging works" | DISCOVER | Read source, write flow doc |
+
+**Phase 1: Identify Target**
+
+Extract the module/topic from user prompt. Map to source directories:
+
+```bash
+# Find relevant source files
+find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) \
+  ! -path "./.git/*" ! -path "./node_modules/*" ! -path "./__pycache__/*" ! -path "./.venv/*" \
+  | xargs grep -l "<keyword>" 2>/dev/null | head -20
+```
+
+**Phase 2: Deep Analysis**
+
+Read the identified files. For each file, extract:
+- **Entry points**: exported functions, route handlers, CLI commands
+- **Data flow**: what goes in → what transformations → what comes out
+- **Dependencies**: imports, external services, databases
+- **Patterns**: design patterns used, conventions followed
+- **Edge cases**: error handling, validation, boundary conditions
+
+**Phase 3: Write Flow Document**
+
+Create `.palbox/flows/<module>.md` using this template:
+
+```markdown
+# [Module Name]
+
+**Discovered:** YYYY-MM-DD
+**Source:** [list of files analyzed]
+**Analysis by:** Lyleen (palskills)
+
+## Entry Points
+| Entry | Type | Source | Description |
+|-------|------|--------|-------------|
+| ... | route/function/class | file:line | ... |
+
+## Data Flow
+[Describe how data moves through this module]
+
+```
+[diagram or step-by-step flow]
+```
+
+## Dependencies
+- **Internal:** [[architecture]], [[methods]]
+- **External:** [list external services/APIs]
+- **Packages:** [key third-party packages]
+
+## Key Patterns
+[Patterns and conventions detected]
+
+## Edge Cases & Error Handling
+[How errors are handled, validation, edge cases]
+
+## Related
+- [[architecture]] — module structure
+- [[methods]] — applicable conventions
+- [[history/]] — past work on this module
+```
+
+**Phase 4: Update Architecture**
+
+If this is a new module not yet in architecture.md, append:
+
+```bash
+echo "- [[flows/<module>]] — [one-line description]" >> .palbox/architecture.md
+```
+
+**Phase 5: Report**
+
+```
+## Lyleen Discovered: [Module] ✓
+
+**Saved:** .palbox/flows/<module>.md
+**Files analyzed:** [N]
+**Architecture updated:** [yes/no]
+
+**Graph after discovery:**
+- Node created: [[flows/<module>]]
+- Edges added: → [[architecture]], [[methods]]
+```
+
 ## Wikilink Conventions
 
 | Syntax | Meaning |
@@ -241,3 +338,5 @@ Return the subgraph to Astralym/Jetdragon. The context is now **relational** —
 6. **Report graph stats** — nodes traversed, links followed, orphans found
 7. **Bootstrap is one-time** — subsequent calls traverse the existing graph
 8. **Bidirectional links matter** — Panthalus maintains them; Lyleen exploits them
+9. **DISCOVER writes to flows/** — when user says "learn/pelajari/discover", save analysis to `.palbox/flows/<module>.md` and update architecture.md
+10. **Panthalus owns history/** — Lyleen never writes to `history/`; that's Panthalus's domain (recording development sessions)