@leejungkiin/awkit 1.0.0

package/skills/ambient-brain/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: ambient-brain
+description: >-
+  Ambient Brain Sync — AI tự động đọc/ghi brain theo context mà không cần user nhớ.
+  Write triggers: decisions, bug fixes, architecture, task completion.
+  Read triggers: session start, debug, new task, errors, similar problems.
+version: 1.0.0
+trigger: always
+priority: high
+---
+
+# 🧠 Ambient Brain Sync
+
+> **Philosophy:** User không nên nhớ để lưu. AI phải tự biết lúc nào cần đọc, lúc nào cần ghi.
+
+---
+
+## Core Principle: "Ambient Memory"
+
+```
+Traditional: User làm việc → nhớ → gõ /save-brain → AI lưu (FAIL khi quên)
+Ambient:     User làm việc → AI tự nhận ra ký ức quan trọng → Tự lưu & tự đọc
+```
+
+---
+
+## 📖 BRAIN READ TRIGGERS (Khi nào tự động ĐỌC)
+
+### R1: Session Start (LUÔN LUÔN)
+**Điều kiện:** Đầu mỗi conversation mới
+```
+Action:
+1. Đọc brain/session.json → Working context
+2. Đọc brain/active_plans.json → Active plan
+3. Đọc brain/decisions/ → 3 decisions gần nhất
+4. Output: Hiển thị "🧠 Brain loaded: [summary]"
+```
+
+### R2: New Task / Feature Work
+**Điều kiện:** User mention file/feature/task cụ thể, hoặc dùng /code, /debug, /plan
+```
+Patterns:
+- "làm feature X", "sửa file Y", "implement Z"
+- /code, /codeExpert, /debug, /debugExpert, /plan, /planExpert
+
+Action:
+1. Query brain/decisions/ với keywords từ task
+2. Query brain/solutions/ với filename/feature name
+3. Nếu tìm thấy liên quan: "💡 Nhớ ra: [relevant context]"
+4. Inject vào working context
+```
+
+### R3: Error / Bug Encounter
+**Điều kiện:** Error message xuất hiện trong conversation
+```
+Patterns (detect any of):
+- "error:", "Error:", "ERROR", "failed:", "exception"  
+- "không chạy", "lỗi", "crash", "bug"
+- Terminal output có stack trace
+
+Action:
+1. Extract error type/keywords
+2. Query brain/solutions/ với error pattern
+3. Nếu tìm thấy: "🔍 Đã gặp lỗi này trước: [solution summary]"
+4. Trình bày solution từ brain trước khi debug mới
+```
+
+### R4: Architectural Decision Needed
+**Điều kiện:** User hỏi về design, approach, architecture
+```
+Patterns:
+- "nên dùng gì", "best approach", "how to design"
+- "chọn giữa X và Y", "architecture", "pattern"
+
+Action:
+1. Query brain/decisions/ với topic
+2. Nếu tìm thấy: "📋 Quyết định cũ: [relevant decision]"
+3. Hỏi: "Vẫn dùng approach này hay muốn thay đổi?"
+```
+
+### R5: Recurring Similar Problem
+**Điều kiện:** Task/error giống với brain entries (keyword overlap > 2)
+```
+Action:
+1. Tự động load solution từ brain
+2. Hiển thị: "🔁 Pattern quen: Đã giải quyết tương tự lúc [date]"
+3. Gợi ý dùng lại solution
+```
+
+---
+
+## 💾 BRAIN WRITE TRIGGERS (Khi nào tự động GHI)
+
+### W1: Decision Made (SILENT AUTO-SAVE)
+**Điều kiện:** AI hoặc user đưa ra quyết định kỹ thuật
+```
+Patterns detect decision:
+- "quyết định dùng...", "ta sẽ dùng...", "chọn approach..."
+- "best way is...", "we'll use...", "decided to..."
+- User confirm sau khi AI suggest: "ok", "được", "đồng ý", "làm vậy đi"
+  (nhưng chỉ sau khi AI vừa đề xuất architecture/approach)
+
+Action (SILENT - không hỏi user):
+1. Extract: what, why, alternatives_considered
+2. Save to: brain/decisions/YYYY-MM-DD-[slug].md
+3. Update: brain/session.json với decision reference
+4. Log internally (không notify user trừ khi được hỏi)
+
+Template:
+---
+date: [ISO date]
+topic: [decision topic]  
+decision: [what was decided]
+rationale: [why this approach]
+alternatives: [other options considered]
+context: [feature/task this belongs to]
+tags: [relevant tags]
+---
+```
+
+### W2: Bug Fixed / Solution Found
+**Điều kiện:** Sau khi fix xong bug được confirm
+```
+Patterns detect resolution:
+- "works now", "fixed", "chạy rồi", "ok rồi", "xong"
+- User sau khi test: "ổn rồi", "pass", "ngon"
+- "solved by", "the fix was"
+
+Action (SILENT):
+1. Capture: error_pattern, root_cause, solution_steps, files_changed
+2. Save to: brain/solutions/[error-slug]-[date].md
+3. Tag với: filename, error_type, feature
+
+Template:
+---
+date: [ISO date]
+error_pattern: [what the error looked like]
+root_cause: [why it happened]
+solution: [how it was fixed]
+files: [which files were changed]
+prevent: [how to avoid in future]
+tags: [file, error_type, feature]
+---
+```
+
+### W3: Architecture / Pattern Defined  
+**Điều kiện:** Sau workflow /plan, /planExpert, /brainstorm hoàn thành; hoặc spec file được tạo
+```
+Action (SILENT):
+1. Capture: feature_name, tech_choices, structure, reasoning
+2. Save to: brain/decisions/arch-[feature]-[date].md
+3. Link to Bead task ID nếu có
+```
+
+### W4: Task Milestone Completed
+**Điều kiện:** `bd update --status done` hoặc user tuyên bố xong 1 giai đoạn lớn
+```
+Patterns:
+- "bd update ... --status done"
+- "xong phase", "hoàn thành feature", "done với X"
+
+Action (SILENT):
+1. Capture: task_name, what_was_built, key_learnings
+2. Append to: brain/session.json → completed_milestones
+3. Nếu có learnings quan trọng → Save to brain/solutions/
+```
+
+### W5: Explicit Save Request
+**Điều kiện:** User gõ /save-brain "title" (vẫn support manual)
+```
+Action (FULL SAVE - có confirm):
+1. Synthesize toàn bộ conversation context
+2. User confirm nội dung trước khi lưu
+3. Save với rich metadata
+4. Notify: "💾 Đã lưu vào brain: [title]"
+```
+
+---
+
+## 🔄 BRAIN SYNC PROTOCOL
+
+### Sync Frequency
+```
+IMMEDIATE (real-time):
+- W1 Decision made → save trong 1 turn
+- W2 Bug fixed → save ngay khi detect resolution
+
+DEFERRED (end of workflow):
+- W3 Architecture → save khi workflow hoàn thành  
+- W4 Task completion → save khi task đóng
+
+PERIODIC:
+- Mỗi 10 turns → Check if anything worth saving missed
+- End of session → Final consolidation save
+```
+
+### File Structure
+```
+brain/
+├── session.json              # Current working state (auto-updated)
+├── active_plans.json         # Plans đang active (auto-updated)  
+├── decisions/
+│   ├── 2026-02-22-use-sqlite.md
+│   ├── 2026-02-22-arch-neural-brain.md
+│   └── ...
+└── solutions/
+    ├── 2026-02-22-fts5-error-fix.md
+    ├── 2026-02-22-activation-algorithm.md
+    └── ...
+```
+
+---
+
+## 🧭 SALIENCE SCORING (Độ quan trọng)
+
+AI tự đánh giá trước khi lưu — chỉ lưu những gì có salience ≥ 0.5:
+
+```
+salience_map:
+  architectural_decision:  0.95  # Always save
+  bug_fix_solution:        0.85  # Always save  
+  tech_choice:             0.80  # Always save
+  pattern_discovered:      0.75  # Save if novel
+  task_completion:         0.60  # Save key learnings
+  code_snippet:            0.50  # Save if reusable
+  conversation_detail:     0.20  # Skip
+  casual_chat:             0.05  # Never save
+```
+
+**Novelty Check:** Nếu brain đã có entry tương tự → Reinforce (tăng salience) thay vì tạo mới.
+
+---
+
+## 🔔 NOTIFICATION BEHAVIOR
+
+```
+QUIET MODE (default):
+- Silent save: Không notify
+- Chỉ show indicator nhỏ: "💾" ở cuối message khi có relevant brain read
+
+VERBOSE MODE (khi user hỏi):  
+- Explain what was saved/loaded
+- Show brain entry preview
+
+NEVER:
+- Hỏi "Bạn có muốn lưu không?" → Chỉ lưu im lặng
+- Interrupt flow để confirm save
+- Spam thông báo lưu
+```
+
+---
+
+## 🧩 INTEGRATION WITH EXISTING SKILLS
+
+```
+Runs BEFORE: session-restore (cung cấp data)
+Runs AFTER:  auto-save (fallback nếu ambient bỏ sót)
+Works WITH:  beads-manager (link brain entries với Bead IDs)
+Enhances:    error-translator (thêm historical context)
+```
+
+---
+
+## 📝 BRAIN QUERY ALGORITHM
+
+Khi đọc brain, AI tự tìm kiếm theo priority:
+
+```
+1. Exact tag match (filename, feature_name, error_type)
+2. Keyword overlap trong content (>= 2 keywords)  
+3. Same time period (cùng feature đang làm)
+4. Recent entries (< 7 ngày)
+
+Return: Top 3 most relevant entries
+Format: Inline mention, không dump toàn bộ content
+```
+
+---
+
+## ⚡ ACTIVATION EXAMPLES
+
+### Example 1: Auto-Read on Error
+```
+User: "Ứng dụng bị crash với lỗi 'TypeError: Cannot read property of undefined'"
+AI internal: [BRAIN READ TRIGGER R3 detected]
+AI scans: brain/solutions/ với "TypeError undefined"  
+AI finds: "2026-02-15-undefined-null-fix.md"
+AI responds: "🔍 Nhớ ra: Lỗi này gặp lần trước do null check thiếu 
+             trong UserService. Fix: optional chaining + default value.
+             Áp dụng vào đây..."
+```
+
+### Example 2: Auto-Write on Decision
+```
+User: "Ok, ta dùng better-sqlite3 cho neural brain"
+AI internal: [BRAIN WRITE TRIGGER W1 detected]
+AI saves silently: brain/decisions/2026-02-22-use-better-sqlite3.md
+AI responds normally (không mention save)
+```
+
+### Example 3: Auto-Read on New Task
+```
+User: "Giờ làm phần activation.js"  
+AI internal: [BRAIN READ TRIGGER R2 detected - filename mention]
+AI scans: brain/* với "activation"
+AI finds: "arch-neural-brain-2026-02-22.md" 
+AI responds: "💡 Từ plan trước: activation.js dùng heap-based BFS với 
+             sigmoid decay. Bắt đầu với SpreadingActivation class..."
+```
+
+---
+
+*ambient-brain v1.0.0 — Auto Memory Sync for AWF*
+*Created by Kien AI*

package/skills/ambient-brain/brain-router.md

@@ -0,0 +1,185 @@
+# Brain Router — Decision Logic
+
+> AI sử dụng file này để quyết định: READ, WRITE, hoặc SKIP brain cho mỗi input.
+
+---
+
+## Routing Decision Tree
+
+```
+USER_INPUT received
+       │
+       ▼
+[1. Session Start?] ──YES──▶ READ: session.json + active_plans + recent decisions
+       │ NO
+       ▼
+[2. Error detected?] ──YES──▶ READ: brain/solutions/ (error pattern match)
+       │ NO                   Then: proceed with debug, WRITE solution if fixed
+       ▼
+[3. Command: /plan, /code, /debug?] ──YES──▶ READ: feature-relevant entries
+       │ NO
+       ▼
+[4. File/Feature/Task mentioned?] ──YES──▶ READ: tag match for that file/feature
+       │ NO
+       ▼
+[5. Decision signal detected?] ──YES──▶ WRITE: brain/decisions/ (silent)
+       │ NO
+       ▼
+[6. Resolution signal detected?] ──YES──▶ WRITE: brain/solutions/ (silent)
+       │ NO
+       ▼
+[7. Workflow end?] ──YES──▶ WRITE: architecture/milestone summary (silent)
+       │ NO
+       ▼
+[8. Every 10 turns?] ──YES──▶ CONSOLIDATE: check missed saves
+       │ NO
+       ▼
+    SKIP (normal processing)
+```
+
+---
+
+## Signal Detection Patterns
+
+### 🔴 WRITE Signals
+
+#### Decision Signals
+```yaml
+high_confidence:
+  - "ta sẽ dùng {X}"
+  - "quyết định dùng {X}"
+  - "chọn {X} vì {reason}"
+  - "best approach là {X}"
+  - "we'll go with {X}"
+  - "decided: {X}"
+
+medium_confidence (chỉ save nếu AI vừa propose):
+  - "ok", "được", "đồng ý"      # + context: AI vừa suggest architecture
+  - "làm vậy đi", "Kien Ok"    # + context: AI vừa propose approach
+  - "alright", "sounds good"    # + context: technical decision context
+
+low_confidence (SKIP - too vague):
+  - "ok" alone in casual chat
+  - "được" in non-technical context
+```
+
+#### Resolution Signals
+```yaml
+high_confidence:
+  - "works now", "fixed it", "chạy rồi"
+  - "problem solved", "issue resolved"
+  - "xong rồi", "ổn rồi", "ngon"
+  - "tests pass", "build success"
+
+medium_confidence:
+  - "ok rồi" sau debug session
+  - "done" sau coding task
+  - emoji: ✅ sau error discussion
+
+requires_context: True  # Chỉ save nếu đang trong debug/fix context
+```
+
+### 🔵 READ Signals
+
+#### Auto-Read Triggers
+```yaml
+session_start:
+  detect: First message of conversation
+  load: session.json, active_plans.json, decisions (last 3)
+  
+error_context:
+  detect: error pattern in message
+  patterns:
+    - "error:", "Error:", "failed", "exception"
+    - "crash", "lỗi", "không chạy", "bug"
+    - Stack trace format (indented lines with "at ")
+  query: brain/solutions/ with error keywords
+  
+task_context:
+  detect: Specific file/feature mentioned + action verb
+  patterns:
+    - "{verb} {filename}.{ext}"
+    - "feature {name}", "implement {name}"
+    - /code, /debug, /plan commands
+  query: brain/* with filename or feature name as tags
+  
+architecture_question:
+  detect: Design/approach question
+  patterns:
+    - "nên dùng gì", "best approach"
+    - "how to design", "architecture for"
+    - "which pattern", "chọn giữa"
+  query: brain/decisions/ with topic keywords
+```
+
+---
+
+## Context Accumulator
+
+Brain Router maintains internal context per conversation:
+
+```json
+{
+  "conversation_context": {
+    "turn_count": 0,
+    "current_feature": null,
+    "current_files": [],
+    "current_task_id": null,
+    "recent_errors": [],
+    "decisions_made": [],
+    "solutions_found": [],
+    "last_brain_read": null,
+    "last_brain_write": null,
+    "brain_entries_loaded": []
+  }
+}
+```
+
+**Updated each turn** to maintain routing accuracy with accumulated context.
+
+---
+
+## Anti-Patterns (When NOT to read/write)
+
+```yaml
+never_read:
+  - Casual greeting ("xin chào", "hi", "how are you")
+  - Pure question about general knowledge (not project-specific)
+  - Already read brain this turn (deduplicate)
+
+never_write:
+  - Salience < 0.5 (see SKILL.md scoring)
+  - Already have identical/similar entry (within 24h)
+  - Casual conversation, non-technical decisions
+  - User says "never mind", "bỏ qua", "thôi"
+
+rate_limits:
+  max_reads_per_turn: 1
+  max_writes_per_turn: 2
+  min_write_interval_seconds: 30  # Avoid duplicate rapid saves
+```
+
+---
+
+## Output Format for Brain Reads
+
+When brain read finds relevant content:
+
+```
+✅ Inline mention (default):
+"💡 Nhớ ra: [1-2 sentence summary]. Áp dụng vào đây..."
+
+✅ Decision reminder:
+"📋 Đã quyết định [X] lúc [date]. Vẫn dùng?"
+
+✅ Solution reference:
+"🔍 Đã giải quyết lỗi tương tự: [root_cause + fix in 1 line]"
+
+❌ Never dump full file content
+❌ Never show raw markdown formatting
+❌ Never mention "reading from brain" explicitly
+```
+
+---
+
+*brain-router v1.0.0 — Routing logic for ambient-brain skill*

package/skills/ambient-brain/brain-templates.md

@@ -0,0 +1,201 @@
+# Brain Entry Templates
+
+> Các template chuẩn để lưu vào brain/ — dùng cho cả auto-save và manual /save-brain.
+
+---
+
+## Template 1: Decision (brain/decisions/)
+
+**Filename:** `brain/decisions/YYYY-MM-DD-[slug].md`
+
+```markdown
+---
+date: 2026-02-22
+type: decision
+topic: [brief topic, e.g., "Database choice for neural-brain"]
+feature: [which feature/project this belongs to]
+tags: [tech, architecture, database, ...]
+salience: 0.90
+---
+
+# Decision: [Topic]
+
+## What was decided
+[Clear statement of the decision]
+
+## Why this approach
+[Rationale — key reasons]
+
+## Alternatives considered
+- **[Option A]**: [Why rejected]
+- **[Option B]**: [Why rejected]
+
+## Trade-offs
+- ✅ [Pro 1]
+- ✅ [Pro 2]
+- ⚠️ [Con/caveat]
+
+## Context
+[Additional context: task ID, feature, constraints]
+```
+
+---
+
+## Template 2: Solution (brain/solutions/)
+
+**Filename:** `brain/solutions/YYYY-MM-DD-[slug].md`
+
+```markdown
+---
+date: 2026-02-22
+type: solution
+error_pattern: [e.g., "TypeError: Cannot read property of undefined"]
+files_affected: [e.g., "activation.js, store.js"]
+tags: [javascript, sqlite, null-check, ...]
+salience: 0.85
+---
+
+# Solution: [Error Pattern]
+
+## The Error
+```
+[Paste exact error or describe the bug]
+```
+
+## Root Cause
+[Why this happened — 1-2 sentences]
+
+## The Fix
+[Step-by-step or code snippet showing the solution]
+
+```js
+// Before (broken)
+code here
+
+// After (fixed)
+code here
+```
+
+## How to Prevent
+[Rule or pattern to avoid this in future]
+
+## Context
+[What feature/task was being worked on when this occurred]
+```
+
+---
+
+## Template 3: Architecture (brain/decisions/)
+
+**Filename:** `brain/decisions/arch-[feature]-[date].md`
+
+```markdown
+---
+date: 2026-02-22
+type: architecture
+feature: [feature name, e.g., "neural-brain"]
+tags: [architecture, design, ...]
+salience: 0.95
+---
+
+# Architecture: [Feature Name]
+
+## Overview
+[Brief description of what was designed]
+
+## Structure
+```
+[directory tree or component diagram]
+```
+
+## Key Decisions
+1. [Decision 1 + rationale]
+2. [Decision 2 + rationale]
+3. [Decision 3 + rationale]
+
+## Tech Choices
+| Component | Choice | Reason |
+|-----------|--------|--------|
+| [Layer]   | [Tech] | [Why]  |
+
+## Data Flow
+[How data flows through the system]
+
+## Open Questions
+- [ ] [Question to resolve later]
+```
+
+---
+
+## Template 4: Session (brain/session.json)
+
+**Auto-updated by ambient-brain skill.**
+
+```json
+{
+  "last_updated": "2026-02-22T16:56:00+07:00",
+  "working_on": {
+    "project": "main-awf",
+    "feature": "neural-brain + ambient-brain skill",
+    "phase": "implementation",
+    "current_task_id": null,
+    "current_files": ["skills/ambient-brain/SKILL.md"]
+  },
+  "recent_decisions": [
+    {
+      "ref": "decisions/2026-02-22-use-better-sqlite3.md",
+      "summary": "Use better-sqlite3 for neural brain storage"
+    }
+  ],
+  "recent_solutions": [],
+  "active_context": {
+    "neural_brain_port": "Planning phase - studying Python source",
+    "ambient_brain": "Implementing skill files"
+  },
+  "completed_milestones": [],
+  "context_checkpoints": []
+}
+```
+
+---
+
+## Template 5: Active Plans (brain/active_plans.json)
+
+```json
+{
+  "plans": [
+    {
+      "id": "neural-brain-nodejs-port",
+      "title": "Port neural-memory to Node.js for main-awf",
+      "status": "planning",
+      "phases": [
+        { "id": "p1", "name": "Study Python source", "status": "done" },
+        { "id": "p2", "name": "Build SQLite schema", "status": "next" },
+        { "id": "p3", "name": "Core data structures", "status": "pending" },
+        { "id": "p4", "name": "Spreading activation engine", "status": "pending" },
+        { "id": "p5", "name": "Public API integration", "status": "pending" }
+      ],
+      "created": "2026-02-22",
+      "last_updated": "2026-02-22"
+    },
+    {
+      "id": "ambient-brain-skill",
+      "title": "Ambient Brain Sync skill for AWF",
+      "status": "implementing",
+      "phases": [
+        { "id": "p1", "name": "Design & brainstorm", "status": "done" },
+        { "id": "p2", "name": "Create skill files", "status": "in_progress" },
+        { "id": "p3", "name": "Update GEMINI.md", "status": "next" },
+        { "id": "p4", "name": "Deploy to antigravity", "status": "pending" },
+        { "id": "p5", "name": "Test with real workflow", "status": "pending" }
+      ],
+      "created": "2026-02-22",
+      "last_updated": "2026-02-22"
+    }
+  ]
+}
+```
+
+---
+
+*brain-templates v1.0.0 — Standard formats for consistent brain storage*