@leejungkiin/awkit 1.0.7 → 1.0.8

package/skills/nm-memory-sync/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: nm-memory-sync
+description: |
+  NeuralMemory-powered ambient brain sync. Replaces flat-file memory-sync with
+  associative graph recall via spreading activation. Auto-reads/writes brain on
+  every session, debug, task, and error — with richer context than keyword matching.
+metadata:
+  stage: core
+  version: "1.0"
+  replaces: memory-sync, ambient-brain
+  requires: neural-memory (pip install neural-memory)
+  tags: [memory, neural, sync, core, ambient]
+agent: Ambient Neural Brain
+allowed-tools:
+  - nmem_remember
+  - nmem_recall
+  - nmem_context
+  - nmem_stats
+  - nmem_auto
+---
+
+# NM Memory Sync — Ambient Neural Brain
+
+> Drop-in upgrade for `memory-sync` and `ambient-brain`.
+> Uses NeuralMemory's spreading activation instead of keyword overlap.
+
+---
+
+## Core Difference vs memory-sync
+
+| Feature | memory-sync (flat-file) | nm-memory-sync (this) |
+|---------|------------------------|----------------------|
+| Storage | Markdown files | SQLite graph (neurons + synapses) |
+| Recall | keyword overlap > 2 | Spreading activation graph |
+| Causality | None | `CAUSED_BY`, `LEADS_TO` links |
+| Time decay | None | Natural decay by age/priority |
+| Dedup | None | Automatic conflict detection |
+| Context | Whole file | Scoped activation subgraph |
+
+---
+
+## READ TRIGGERS (Auto-Read từ Brain)
+
+### R1: Session Start
+**Condition:** Conversation bắt đầu
+**Action:** `nmem_context()` → load recent + high-activation memories
+**Output:** Silent loading, brief summary nếu relevant
+
+### R2: New Task / Debugging
+**Condition:** User bắt đầu task mới hoặc debug session
+**Action:** `nmem_recall(task_keywords)` → associative recall
+**Output:** Show relevant decisions, past errors, solutions
+
+### R3: Error Encountered
+**Condition:** Exception, crash, hoặc lỗi xuất hiện
+**Action:** `nmem_recall(error_type + keywords)` → find past similar errors
+**Output:** Auto-propose known solutions if confidence > 0.7
+
+### R4: Architecture Question
+**Condition:** User hỏi về design, pattern, tech choice
+**Action:** `nmem_recall(topic, depth=3)` → deep associative recall
+**Output:** Related decisions, constraints, context
+
+### R5: Recurring Problem (Enhanced)
+**Condition:** Vấn đề tương tự đã gặp (spreading activation detects similarity)
+**Action:** Activate related memory cluster
+**Output:** "🧠 Similar to [memory]: [solution]" — NO keyword threshold needed
+
+---
+
+## WRITE TRIGGERS (Auto-Write vào Brain)
+
+### W1: Decision Made → `decision` type
+**Condition:** AI hoặc user đưa ra quyết định kỹ thuật
+**Capture:** "Chose X because Y" format
+**Store:** `nmem_remember(content, type="decision", priority=7)`
+**Links:** Auto-link to related memories via NeuralMemory engine
+
+### W2: Bug Fixed → `error` type
+**Condition:** User confirm fix thành công ("xong", "ok", "chạy rồi")
+**Capture:** Error + root cause + solution
+**Store:** `nmem_remember(content, type="error", priority=8)`
+**Links:** `CAUSED_BY` → triggering condition, `LEADS_TO` → fix applied
+
+### W3: Architecture Change → `instruction` type
+**Condition:** File structure thay đổi, pattern mới được áp dụng
+**Capture:** What changed + why
+**Store:** `nmem_remember(content, type="instruction", priority=7)`
+**Links:** `SUPERSEDES` → old pattern if exists
+
+### W4: Task Complete → `workflow` type
+**Condition:** Task marked done trong Beads
+**Capture:** What was done + approach taken
+**Store:** `nmem_remember(content, type="workflow", priority=5)`
+
+### W5: User Preference Detected → `preference` type
+**Condition:** User consistently uses pattern or expresses preference
+**Capture:** The preference + context
+**Store:** `nmem_remember(content, type="preference", priority=6)`
+
+---
+
+## Sync Protocol
+
+### Session Start Flow
+```
+1. nmem_context() → get active memory cluster
+2. Filter by project tags (from .project-identity if available)
+3. SILENT load — no output unless > 3 highly relevant memories
+4. If relevant: "🧠 Recalled: [brief summary]"
+```
+
+### Error Flow
+```
+1. Extract: error_type, file, function, keywords
+2. nmem_recall(f"{error_type} {keywords}", depth=2)
+3. If match (activation > 0.6):
+   → "🧠 Similar error: [past error] — Solution: [fix]"
+4. After fix confirmed:
+   → nmem_remember(error + solution, type="error", tags=[...])
+   → Create CAUSED_BY + LEADS_TO synapses
+```
+
+### Decision Write Flow
+```
+1. Detect decision signal words: "chose", "decided", "going with", "will use"
+2. Extract: choice + reason (requires both for quality decision memory)
+3. nmem_recall(topic) → check for conflicts
+4. SILENT store: nmem_remember(content, type="decision", priority=7)
+5. Confirm: "💾 Saved decision: [brief]"
+```
+
+---
+
+## Associative Recall Strategy
+
+Unlike keyword overlap (old memory-sync), nm-memory-sync uses:
+
+```
+Query: "API authentication failing"
+         ↓ spreading activation
+Anchor neurons: [api, auth, fail]
+         ↓ activate synapses (depth=2)
+Related neurons: [jwt, token, session, middleware]
+         ↓ intersect top activations
+Surface memories: 
+  - "Decided JWT over sessions for stateless API" (decision, auth tags)
+  - "Fixed middleware order causing 401" (error, api tags)
+  - "Never store tokens in localStorage" (instruction, security tags)
+```
+
+This surfaces memories that a keyword search would miss.
+
+---
+
+## Notification Behavior
+
+| Event | Output |
+|-------|--------|
+| Relevant memory found (activation > 0.7) | `🧠 [brief recall]` |
+| Decision auto-saved | `💾 Saved: [brief]` |
+| Bug solution stored | `🔧 Stored fix: [brief]` |
+| No relevant memory | Silent (no output) |
+| Conflict detected | `⚠️ Conflicts with: [memory]` |
+
+---
+
+## Fallback Mode (NeuralMemory Not Installed)
+
+If `nmem` is not available, falls back to flat-file behavior:
+```
+- Reads from brain/decisions/, brain/solutions/
+- Keyword overlap matching (legacy behavior)
+- Shows warning once: "⚠️ NeuralMemory not installed. Using flat-file fallback."
+```
+
+---
+
+## Integration
+
+- Works alongside `beads-manager` for task lifecycle hooks
+- Reads `.project-identity` for project-scoped memory filtering
+- Feeds data to `nm-memory-audit` for quality checks
+- Activated before `orchestrator` dispatches (priority 2.5 in skill chain)

package/skills/orchestrator/SKILL.md

@@ -3,32 +3,33 @@ name: orchestrator
 description: >-
   Intelligent dispatcher — analyzes context, injects project brain, then
   delegates to the right skill or workflow. Always runs first.
-version: 2.0.0
+invocation-type: auto
+version: 2.1.0
 trigger: always
 priority: 1
 ---
 
-# Orchestrator Skill v2.0 — Project-Aware
+# Orchestrator Skill v2.1 — Project-Aware + Self-Evolving
 
 > **Role:** First-layer processor. Chạy trước MỌI skill khác.
-> **New in v2.0:** Project Brain Lookup — inject project context trước khi route.
+> **v2.0:** Project Brain Lookup — inject project context trước khi route.
+> **v2.1:** Self-Evolution Pattern — tự ghi learnings sau mỗi session.
 
 ---
 
 ## Execution Order (MANDATORY)
 
 ```
-Step 1: Project Brain Lookup    ← MỚI — chạy đầu tiên
+Step 1: Project Brain Lookup    ← chạy đầu tiên
 Step 2: Intent Detection
 Step 3: Route to skill/workflow
+Step 4: Self-Evolution          ← ghi learnings nếu có
 ```
 
 ---
 
 ## Step 1: Project Brain Lookup (LUÔN CHẠY)
 
-Trước khi làm bất cứ điều gì, orchestrator phải load project context:
-
 ### 1.1 — Đọc `.project-identity`
 
 ```yaml
@@ -38,10 +39,9 @@ IF EXISTS:
   read: .project-identity
   extract:
     - projectName
-    - stage (stage3_development, etc.)
+    - stage
     - architecture (clean_architecture, mvvm)
     - tech stack (swift, react, node, etc.)
-    - currentWork / nextMilestones
 
 SET: project_context = { name, stage, arch, stack }
 ```
@@ -57,9 +57,6 @@ IF EXISTS:
     - layer_map: { layer_name → files[] }
     - feature_areas: { feature → directory }
     - naming_conventions
-    - data_flow_diagrams
-
-SET: codebase_map = { layers, features, conventions }
 
 RULES:
   → KHÔNG scan raw directory nếu CODEBASE.md tồn tại
@@ -69,15 +66,11 @@ RULES:
 ### 1.3 — Resolve Target từ Request
 
 ```yaml
-# Khi user đề cập feature/bug/area:
 resolve_target(user_request, codebase_map):
-  keywords = extract_keywords(user_request)
-  
-  # Match theo thứ tự ưu tiên:
-  1. Layer match: "crash khi login" → AuthenticationViewModel, AuthUseCases
+  1. Layer match: "crash khi login" → AuthenticationViewModel
   2. Feature match: "water tracking" → Features/Water/
-  3. Service match: "camera chậm" → CameraViewModel + Core/Services/
-  4. Fallback: "không rõ" → list top 3 candidates từ CODEBASE.md
+  3. Service match: "camera chậm" → CameraViewModel
+  4. Fallback: list top 3 candidates từ CODEBASE.md
 ```
 
 ### 1.4 — Brief Confirm Output (LUÔN HIỂN THỊ)
@@ -87,27 +80,17 @@ Format:
   "📚 [ProjectName] | [Stage] | [Architecture]
    🗺️  Targeting: [resolved file/layer]"
 
-Example:
-  "📚 FitBite Witness | Stage 3 Development | Clean Architecture + MVVM
-   🗺️  Targeting: AuthenticationViewModel → SignInUseCase"
-
-Nếu CODEBASE.md không có:
-  "📚 [ProjectName] — CODEBASE.md chưa có, đang scan cấu trúc..."
-
-Nếu file được nhắc đến KHÔNG có trong CODEBASE.md:
-  → Thực hiện xong, thêm footer: "⚠️ CODEBASE.md có thể outdated — dùng /codebase-sync"
+Nếu file được nhắc KHÔNG có trong CODEBASE.md:
+  → Footer: "⚠️ CODEBASE.md có thể outdated — dùng /codebase-sync"
 ```
 
 ---
 
 ## Step 2: Intent Detection
 
-Sau khi có project context, detect intent từ request:
-
 ```yaml
 debug_intent:
   keywords: ["error", "bug", "crash", "fix", "lỗi", "sửa", "fail", "không chạy"]
-  + image: [screenshot of error/crash]
   action: Execute debug flow với target đã resolve từ Step 1
 
 code_intent:
@@ -145,25 +128,16 @@ image_intent:
 → Không hỏi "file này ở đâu?" — đã biết từ CODEBASE.md
 ```
 
-### Without Project Context
-
-```
-→ Route bình thường theo intent
-→ Suggest workflow phù hợp
-→ Có thể hỏi clarifying question (max 2 lần)
-```
-
 ### Slash Command Detection
 
 ```yaml
-# User gõ /command → Load workflow file trực tiếp
-/plan        → global_workflows/plan.md
-/planExpert  → global_workflows/planExpert.md
-/code        → global_workflows/code.md
-/codeExpert  → global_workflows/codeExpert.md
-/debug       → global_workflows/debug.md
-/debugExpert → global_workflows/debugExpert.md
-/codebase-sync → global_workflows/codebase-sync.md  # MỚI
+/plan        → workflows/lifecycle/plan.md
+/planExpert  → workflows/lifecycle/planExpert.md
+/code        → workflows/lifecycle/code.md
+/codeExpert  → workflows/lifecycle/codeExpert.md
+/debug       → workflows/lifecycle/debug.md
+/debugExpert → workflows/lifecycle/debugExpert.md
+/codebase-sync → workflows/context/codebase-sync.md
 # ...etc (see GEMINI.md)
 ```
 
@@ -176,18 +150,35 @@ Still unclear   → Suggest /help
 
 ---
 
+## Step 4: Self-Evolution Protocol
+
+After each session, if a routing decision was suboptimal or a new intent was discovered:
+
+1. **Record** the finding in the Learnings section below
+2. **Update** routing rules in Step 2 if a new keyword pattern should be added
+3. **Cross-check** skill catalog (`skills/CATALOG.md`) to ensure new skills are routable
+
+> This ensures the orchestrator improves its routing accuracy over time.
+
+## Learnings
+
+_Findings from past sessions are recorded here. Add new entries as bullet points._
+
+- v2.0: Added project brain lookup — significantly reduces unnecessary questions about file locations.
+- v2.1: Added self-evolution pattern — skill now self-improves by recording routing insights.
+- `invocation-type` field added to help distinguish auto vs manual skills in routing decisions.
+
+---
+
 ## Integration
 
 ```yaml
 runs_before: awf-session-restore, memory-sync, all workflows
 provides_to: [project_context, resolved_target, intent]
 receives_from: user_request, active_document
-
-# Khi có CODEBASE.md → memory-sync R2 chỉ cần query với resolved_target
-# thay vì query toàn bộ brain/
 ```
 
 ---
 
-*orchestrator v2.0 — Project-Aware Dispatcher*
+*orchestrator v2.1 — Project-Aware + Self-Evolving Dispatcher*
 *Created by Kien AI*

package/skills/schemas/brain-snapshot.json

@@ -0,0 +1,167 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "NeuralMemory Brain Snapshot",
+    "description": "Schema for nm-snapshot exported brain state — Portable Consciousness",
+    "type": "object",
+    "required": [
+        "version",
+        "exported_at",
+        "memories",
+        "synapses"
+    ],
+    "properties": {
+        "version": {
+            "type": "string",
+            "const": "1.0"
+        },
+        "exported_at": {
+            "type": "string",
+            "format": "date-time"
+        },
+        "project": {
+            "type": "string",
+            "description": "Project name from .project-identity"
+        },
+        "scope": {
+            "type": "string",
+            "enum": [
+                "full",
+                "topic",
+                "recent",
+                "high-priority"
+            ]
+        },
+        "memories": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": [
+                    "id",
+                    "content",
+                    "type",
+                    "priority",
+                    "created_at"
+                ],
+                "properties": {
+                    "id": {
+                        "type": "string"
+                    },
+                    "content": {
+                        "type": "string"
+                    },
+                    "type": {
+                        "type": "string",
+                        "enum": [
+                            "fact",
+                            "decision",
+                            "todo",
+                            "error",
+                            "insight",
+                            "preference",
+                            "instruction",
+                            "workflow",
+                            "context"
+                        ]
+                    },
+                    "priority": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 10
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "created_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "expires_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "activation_score": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                    },
+                    "recall_count": {
+                        "type": "integer",
+                        "minimum": 0
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": [
+                            "active",
+                            "archived",
+                            "expired"
+                        ]
+                    }
+                }
+            }
+        },
+        "synapses": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": [
+                    "from_id",
+                    "to_id",
+                    "type",
+                    "weight"
+                ],
+                "properties": {
+                    "from_id": {
+                        "type": "string"
+                    },
+                    "to_id": {
+                        "type": "string"
+                    },
+                    "type": {
+                        "type": "string",
+                        "enum": [
+                            "CAUSED_BY",
+                            "LEADS_TO",
+                            "DISCUSSED",
+                            "CONTRADICTS",
+                            "SUPERSEDES",
+                            "COMPLEMENTS",
+                            "RELATED"
+                        ]
+                    },
+                    "weight": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                    },
+                    "created_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    }
+                }
+            }
+        },
+        "stats": {
+            "type": "object",
+            "properties": {
+                "total_memories": {
+                    "type": "integer"
+                },
+                "total_synapses": {
+                    "type": "integer"
+                },
+                "avg_priority": {
+                    "type": "number"
+                },
+                "active_memories": {
+                    "type": "integer"
+                },
+                "archived_memories": {
+                    "type": "integer"
+                }
+            }
+        }
+    }
+}

package/skills/skills/nm-memory-audit/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: nm-memory-audit
+description: |
+  6-dimension quality review of NeuralMemory brain health.
+  Grades each dimension (A-F), produces graded findings, and recommends
+  concrete actions for improvement. Run weekly or before major sprints.
+metadata:
+  stage: review
+  version: "1.0"
+  requires: neural-memory (pip install neural-memory)
+  tags: [memory, audit, quality, review, neuralmemory]
+agent: Memory Quality Inspector
+trigger:
+  commands: ["/memory-audit", "/nm-audit"]
+  keywords: ["audit brain", "check memory", "memory health"]
+allowed-tools:
+  - nmem_recall
+  - nmem_stats
+  - nmem_context
+---
+
+# NM Memory Audit — Memory Quality Inspector
+
+> Systematic quality review of the NeuralMemory brain.
+> Grades memory health across 6 dimensions, surfaces actionable findings.
+
+## Trigger
+
+```
+/memory-audit
+/nm-audit
+```
+
+---
+
+## 6 Audit Dimensions
+
+### 1. Purity (A-F)
+**Question:** Are memories well-typed and single-concept?
+
+Check for:
+- Mixed types in one memory (fact + decision combined)
+- Vague or generic content ("fixed a bug" → F)
+- Missing source attribution
+- Over-broad scope ("everything about auth")
+
+**Grade:**
+- A: 90%+ memories are single-concept, well-typed
+- B: 75-89% clean
+- C: 60-74% — noticeable clutter
+- D: 40-59% — significant cleanup needed
+- F: <40% — urgent restructuring required
+
+### 2. Freshness (A-F)
+**Question:** Are memories still current and relevant?
+
+Check for:
+- Expired memories (past TTL) still active
+- Outdated decisions (superseded but not marked)
+- Stale context (project state changed)
+- Memories about deprecated features/APIs
+
+**Grade based on:** % expired / stale vs total
+
+### 3. Coverage (A-F)
+**Question:** Are important areas of the project well-documented?
+
+Check for:
+- Core architecture decisions — present? complete?
+- Recent bugs/fixes — all captured?
+- Team preferences — documented?
+- Onboarding knowledge — accessible?
+
+**Grade based on:** Key areas vs documented areas ratio
+
+### 4. Clarity (A-F)
+**Question:** Can memories be understood without context?
+
+Check for:
+- Jargon without explanation ("the THING was fixed")
+- Missing who/what/why ("updated it")
+- Inconsistent terminology (same concept, multiple names)
+- Vietnamese/English mixing without clear pattern
+
+**Grade based on:** Avg clarity score across sampled memories
+
+### 5. Relevance (A-F)
+**Question:** Are memories being recalled and used?
+
+Check for:
+- Low-activation memories (never recalled in 30d)
+- Duplicate memories competing for activation
+- Orphaned memories (no synapse connections)
+- Memories blocking relevant recall (noise)
+
+**Grade based on:** Recall frequency + synapse connectivity
+
+### 6. Structure (A-F)
+**Question:** Is the synapse graph healthy?
+
+Check for:
+- Isolated neurons (no connections)
+- Missing causal links (decisions without causes)
+- Tag inconsistency (similar concepts, different tags)
+- Temporal gaps (events without before/after links)
+
+**Grade based on:** Graph connectivity metrics from nmem_stats
+
+---
+
+## Output Format
+
+```
+🔍 Memory Brain Audit — [date]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Health Overview
+  Total memories: 127
+  Active (recalled 7d): 43 (34%)
+  Expired/stale: 12 (9%)
+  Orphaned neurons: 8 (6%)
+
+📋 Dimension Grades
+  Purity:    B (78%) — Some mixed-concept memories found
+  Freshness: A (92%) — Brain is current ✨
+  Coverage:  C (61%) — Auth and deploy areas sparse
+  Clarity:   B (80%) — Minor jargon issues
+  Relevance: B (75%) — 8 orphaned low-priority memories
+  Structure: C (65%) — Missing causal links in 15 decisions
+
+Overall: B- (75%)
+
+🔴 Critical Findings (fix now)
+  1. 3 expired `todo` memories still active — run /memory-evolution to prune
+  2. Auth architecture has no decision memories — document now
+
+🟡 Moderate Findings (fix this week)
+  3. 8 orphaned memories — no synapse connections
+  4. "deployment" and "deploy" tags used inconsistently (15 memories)
+
+🟢 Minor Findings (optional)
+  5. 5 memories could be split into smaller single-concept memories
+  6. 3 decisions missing "because Y" reasoning
+
+💡 Recommended Next Step
+  Run: /memory-evolution "prune expired, fix auth coverage"
+```
+
+---
+
+## Rules
+
+- Always show the full 6-dimension breakdown
+- Never modify memories during audit — report only
+- Grade based on objective metrics when possible
+- Prioritize by impact: Critical > Moderate > Minor
+- End with one concrete "next step" recommendation