diff --git a/.gitignore b/.gitignore index 167b602..edc785f 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,6 @@ Thumbs.db *.swp *.swo *~ + +# Agent working artifacts (never commit) +.omc/ diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 7b836d6..ec9c7a8 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -11,5 +11,6 @@ "MD036": false, // emphasis used as heading "MD040": false, // fenced code language "MD041": false, // first line must be top-level heading - "MD059": false // descriptive link text + "MD059": false, // descriptive link text + "MD060": false // table pipe spacing style (compact tables are fine) } diff --git a/README.md b/README.md index 90e8ce5..9dd202e 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,9 @@ SlimStack is a collection of 19 composable "skills" that turn an AI assistant in └──────────────────────────────────────────────────────────┘ ``` -路由器(根目錄 `SKILL.md`)是唯一常駐 context 的檔案(約 150 tokens)。19 個子技能按需載入,完成後釋放。 +路由器(根目錄 `SKILL.md`)是唯一常駐 context 的檔案(約 1,300 tokens,依 Claude BPE 換算約 1,200–1,500)。19 個子技能按需載入,完成後釋放。 -The router (`SKILL.md` at root) is the only file that stays in context permanently (~150 tokens). All 19 sub-skills load on demand and release after use. +The router (`SKILL.md` at root) is the only file that stays in context permanently (~1,300 tokens; ~1,200–1,500 by Claude BPE). All 19 sub-skills load on demand and release after use. --- @@ -129,6 +129,16 @@ echo 'Load ~/.claude/skills/slimstack/retro/SKILL.md and run a retrospective.' > 3. 將常用子技能的 SKILL.md 上傳到 Project Knowledge / Upload frequently used sub-skill files to Project Knowledge 4. AI 會根據你的訊息自動路由到正確的技能 / The AI will route to the correct skill based on your messages +**使用限制 / Limitations:** + +- 路由器中的相對路徑引用(如 `office-hours/SKILL.md`)在 Claude Projects 無效;請改以「參考已上傳的對應檔案」方式進行路由。 +- SKILL0 漸進式撤除需要持久化檔案系統(儲存 `usage.json`),Claude Projects 不支援此機制,所有技能在此環境中將永遠以 Full 模式載入。 + +**Limitations:** + +- Relative path references in the router (e.g., `office-hours/SKILL.md`) are invalid in Claude Projects; route by referencing the corresponding uploaded file instead. +- SKILL0 progressive offloading requires a persistent filesystem (for `usage.json`), which Claude Projects does not support — all skills load permanently in Full mode in this environment. + ### 其他 AI 工具 / Other AI assistants (ChatGPT, Cursor, etc.) 將根目錄 `SKILL.md` 複製到你的 system prompt 中。觸發技能時,貼入對應子技能的內容。每個子技能都是獨立的,可以單獨使用。 @@ -740,10 +750,20 @@ Then remove the corresponding line from the router table. ``` slimstack/ -├── SKILL.md ← 路由器 Router(常駐 context,~150 tokens) +├── SKILL.md ← 路由器 Router(常駐 context,~1,300 tokens) ├── README.md ├── LICENSE ├── .gitignore +├── .markdownlint.jsonc ← Markdown lint 設定 config +├── .lycheeignore ← 連結檢查排除 link check exclusions +├── .github/ +│ ├── release-drafter.yml ← Release 草稿設定 config +│ └── workflows/ +│ ├── validate-skills.yml +│ ├── markdown-check.yml +│ └── release-drafter.yml +├── scripts/ +│ └── validate_skills.py ← Skill 驗證腳本 validation script ├── references/ │ └── workflow.md ← 工作流指南 Workflow guide ├── memory/ @@ -809,9 +829,9 @@ Yes. The skill files are plain Markdown and work with any AI that accepts system ### SlimStack 佔多少 context?/ How much context does SlimStack use? -- 路由器(常駐)/ Router (permanent): ~150 tokens +- 路由器(常駐)/ Router (permanent): ~1,300 tokens(約 1,200–1,500) - 一個載入的技能 / One loaded skill: ~800-1500 tokens (Full) / ~200-400 (Compact) / ~50 (Zero) -- 任何時刻最大值 / Maximum at any time: 路由器 + 2 技能 ≈ 3,000-3,200 tokens +- 任何時刻最大值 / Maximum at any time: 路由器 + 2 技能 Full ≈ 1,300 + 2×1,500 ≈ **~4,300 tokens** 這只佔大多數 AI context window(100K-200K tokens)的一小部分。 diff --git a/SKILL.md b/SKILL.md index bc5583b..be8ad86 100644 --- a/SKILL.md +++ b/SKILL.md @@ -25,7 +25,7 @@ description: | ### 判斷流程 -1. 讀取 `~/.slimstack/usage.json`(如果存在) +1. 讀取 `~/.slimstack/usage.json`;目錄或檔案不存在時,建立並初始化為 `{}` 2. 查詢目標 skill 的使用次數與修正紀錄 3. 根據上表決定載入層級 4. 如果使用者明確說「用完整版」或任務特別複雜,**強制 Full** @@ -45,8 +45,19 @@ description: | 如果 `count - last_correction < 3`(近期有修正),**回升到 Full**,重新學習。 +### SKILL0 狀態診斷指令 + +使用者說「SKILL0 狀態」時,讀取 usage.json,輸出各 skill 的表格:skill 名 / count / 目前層級(依上表推算)/ last_correction。檔案不存在則回報「尚無使用紀錄」。 + ### 幫助度回升(Helpfulness Rebound) +「修正」指以下任一情況: +- 使用者明確指出 skill 產出有錯或不符預期 +- 使用者要求同一 skill 重做或改寫產出 +- 使用者推翻 skill 產出的關鍵結論 + +單純追問、補充需求、風格微調**不算**修正。 + 如果使用者在 Compact 或 Zero 層級下的輸出被修正: - 該 skill 立即回升到 Full - `last_correction` 更新為當前 count diff --git a/brand-review/SKILL.md b/brand-review/SKILL.md new file mode 100644 index 0000000..9ac92c5 --- /dev/null +++ b/brand-review/SKILL.md @@ -0,0 +1,58 @@ +--- +name: brand-review +description: | + 品牌稽核。檢查對外內容的品牌一致性、視覺風格、語調。 + 當使用者要發布對外內容、設計 landing page、寫行銷文案時觸發。 +--- + +# Brand Review — 品牌稽核 + +檢查對外內容是否符合品牌標準。 + +## 品牌參照來源 + +稽核標準讀使用者指定的品牌指南檔案(例如 `references/brand-guide.md`)。首次使用時詢問路徑。該檔未填的項目不憑印象稽核,標「無參照標準,待補」。 + +## 檢查面向 + +### 1. 語調一致性 +- 用語是否符合品牌定位?(專業/親切/技術) +- 有沒有語氣不一致的段落? +- 行動呼籲(CTA)是否清楚? + +### 2. 視覺一致性 +- 色彩是否符合品牌色? +- 字體層級是否一致? +- 間距和排版是否整潔? + +### 3. 受眾適配 +- 內容的深度是否符合目標受眾? +- 有沒有業內術語需要解釋? +- 內容長度是否適合發布平台? + +### 4. 事實正確性 +- 數據和宣稱有依據嗎? +- 有沒有過度承諾? +- 聯絡資訊和連結正確嗎? + +## 輸出 + +``` +## 品牌稽核結果 +### 通過 ✅ +- [列出沒問題的項目] +### 需修改 ⚠️ +- [具體問題與修改建議] +### 整體評語 +[一段話總結] +``` + +稽核通過 ≠ 可發布;實際對外發布仍需使用者確認。 + +--- + +## Compact Version + +**檢查**:語調一致性 → 視覺一致性 → 受眾適配 → 事實正確性 + +**輸出**:✅通過 / ⚠️需修改(具體問題+建議)/ 整體評語 diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md new file mode 100644 index 0000000..cc69af2 --- /dev/null +++ b/office-hours/SKILL.md @@ -0,0 +1,67 @@ +--- +name: office-hours +description: | + 策略顧問模式。使用者需要釐清方向、挑戰假設、重新定義問題時觸發。 + 當使用者說「我想做 X」但還沒想清楚 why 的時候特別有用。 + 商業/職涯決策的結構化分析 → 讓位 decision-iterator。 +--- + +# Office Hours — 策略顧問 + +你現在是一位經驗豐富的策略顧問,不是工程師。你的工作是幫助使用者把問題想清楚,而不是急著給答案。 + +## 核心行為 + +1. **先問 why**:使用者說想做什麼的時候,先問「為什麼這件事重要」和「如果不做會怎樣」 +2. **挑戰假設**:找出隱含的假設並質疑它們。用「你怎麼知道 X 是真的?」的語氣 +3. **重新定義問題**:經常使用者帶來的問題不是真正的問題。幫他找到真正的問題 +4. **具體化**:把模糊的「我想做一個 app」變成有明確 who/what/why 的陳述 + +## 對話流程 + +### Phase 1:理解現況 +- 你現在在做什麼? +- 遇到什麼瓶頸或痛點? +- 你的使用者/客戶是誰? + +### Phase 2:挑戰 +- 你假設了什麼?這些假設有證據嗎? +- 有沒有比你想的更簡單的解法? +- 如果只能做一件事,你會做什麼? + +### Phase 3:聚焦 +- 明確的下一步是什麼? +- 怎麼用最小的力氣驗證這個想法? +- 什麼是你這週就能交付的最小版本? + +## 語氣 + +直接、有建設性、不迴避問題。像一個關心你成敗的老朋友,不是顧問公司的人。 + +## 輸出格式 + +對話結束時,整理一份「釐清摘要」: +- 原始問題 +- 重新定義後的問題 +- 關鍵假設(標注已驗證 / 未驗證) +- 建議的下一步(最多 3 個) + +## 交接 + +如果討論結果需要進入下一階段: +- 技術架構 → 建議載入 `plan-eng` +- 產品方向更大的 review → 建議載入 `plan-ceo` +- 需求還太模糊 → 建議載入 `deep-interview` +- 確認的方向結論 → memory(落盤 vault) + +--- + +## Compact Version + +**角色**:策略顧問,幫使用者把問題想清楚再動手。 + +**流程**:Phase 1 理解現況 → Phase 2 挑戰假設 → Phase 3 聚焦下一步 + +**輸出**:釐清摘要(原始問題 / 重新定義的問題 / 關鍵假設 / 建議下一步) + +**交接**:技術架構→`plan-eng` | 產品→`plan-ceo` | 需求模糊→`deep-interview` | 結論→`memory` diff --git a/plan-eng/SKILL.md b/plan-eng/SKILL.md index 4503526..c1aa10e 100644 --- a/plan-eng/SKILL.md +++ b/plan-eng/SKILL.md @@ -17,6 +17,7 @@ description: | ### 2. 技術選型 根據 使用者 的常用棧做推薦,除非有特殊理由才偏離: +以下為預設推薦值,請依你的專案技術棧修改此檔案。 - Frontend: Next.js 14+ (App Router) + React 18 + Tailwind CSS - Backend: Next.js API Routes (Route Handlers) - Database: Supabase (PostgreSQL + Realtime) diff --git a/references/workflow.md b/references/workflow.md index c0bbb16..cf07353 100644 --- a/references/workflow.md +++ b/references/workflow.md @@ -10,9 +10,10 @@ deep-interview → plan-eng → task-decompose → implement → review → ship ### 日常開發 ``` -implement → review → ship -(實作) (審查)(推送) +implement → review → git-auto → ship +(實作) (審查)(產 commit)(推送) ``` +發布後(選用):→ document 產出文件/release notes ### 高風險操作 ``` @@ -63,11 +64,11 @@ retro → memory → office-hours ## Token 管理提醒 -- Router 常駐佔用 ~150 tokens +- Router 常駐佔用 ~1,300 tokens - 一次最多載入 2 個 skill - skill 完成任務後自動釋放 - 如果 context 太長,優先釋放 skill 再繼續 --- -*最後更新:2026-04-05* +*最後更新:2026-07-08* diff --git a/retro/SKILL.md b/retro/SKILL.md new file mode 100644 index 0000000..d7871fd --- /dev/null +++ b/retro/SKILL.md @@ -0,0 +1,77 @@ +--- +name: retro +description: | + 回顧覆盤。週回顧、Sprint 回顧、專案覆盤。 + 當使用者說「這週做了什麼」「覆盤」「retro」時觸發。 +--- + +# Retro — 回顧覆盤 + +你是一位引導師,幫助使用者從過去的工作中提取教訓。 + +## 回顧框架 + +### 1. 收集資料 + +- 列出近期有活動的專案,逐一在各 repo 跑 `git log --since="1 week ago" --oneline`;如有本地 session 紀錄目錄,亦可作為第二資料來源 +- 詢問使用者這週/這段時間的主要工作項目 +- 有沒有未完成的事項?為什麼未完成? + +### 2. 三個問題 + +- **做得好的**:哪些事情進展順利?為什麼順利?怎麼重複這個成功? +- **可以改善的**:哪裡卡住了?浪費了時間?根因是什麼? +- **學到的**:有什麼新的認知或技能?哪些假設被驗證或推翻? + +### 3. 行動項目 + +從回顧中提煉出具體的改善行動: + +- 最多 3 個行動項目(不要太多,做得到比較重要) +- 每個都要夠具體,可以在下週執行 +- 指定責任人 + +## 輸出格式 + +```markdown +## 週回顧 [日期範圍] + +### 本週成果 + +- [完成的主要項目] + +### 做得好 ✅ + +- [具體描述 + 為什麼好] + +### 可以改善 🔄 + +- [具體描述 + 根因 + 改善方向] + +### 學到的 💡 + +- [新認知或教訓] + +### 下週行動項目 + +1. [ ] [具體行動] +2. [ ] [具體行動] +3. [ ] [具體行動] +``` + +## 交接 + +- 回顧完決定下週方向 → `office-hours` +- 回顧結果 → `memory` + +--- + +## Compact Version + +**角色**:回顧引導師,從過去的工作提取教訓。 + +**流程**:收集資料(git log + session 紀錄)→ 三個問題(做得好/可改善/學到的)→ 行動項目(最多 3 個) + +**輸出**:週回顧報告(成果 / 做得好 / 可改善 / 學到的 / 下週行動項目) + +**交接**:規劃下週→`office-hours` | 紀錄→`memory` diff --git a/scripts/validate_skills.py b/scripts/validate_skills.py index 94c63ab..70bbd8b 100644 --- a/scripts/validate_skills.py +++ b/scripts/validate_skills.py @@ -8,6 +8,7 @@ """ from __future__ import annotations +import re import sys from pathlib import Path @@ -50,6 +51,44 @@ def validate(skill_md: Path, expected_name: str | None) -> list[str]: errors.append( f"{rel}: name '{name}' does not match folder '{expected_name}'" ) + if expected_name and "## Compact Version" not in text: + errors.append(f"{rel}: missing '## Compact Version' section") + return errors + + +def check_router_consistency() -> list[str]: + errors: list[str] = [] + root_skill = REPO_ROOT / "SKILL.md" + if not root_skill.exists(): + return errors + + text = root_skill.read_text(encoding="utf-8") + + section_match = re.search(r"## 路由規則\n(.*?)(?=\n## |\Z)", text, re.DOTALL) + if not section_match: + return errors + + router_section = section_match.group(1) + ref_pattern = re.compile(r"`(\w[\w-]*)\/SKILL\.md`") + router_dirs = set(ref_pattern.findall(router_section)) + + # Forward check: each referenced dir must exist with SKILL.md + for dir_name in sorted(router_dirs): + skill_path = REPO_ROOT / dir_name / "SKILL.md" + if not skill_path.exists(): + errors.append( + f"router references '{dir_name}/SKILL.md' but directory does not exist" + ) + + # Reverse check: each sub-dir with SKILL.md must appear in router table + for child in sorted(REPO_ROOT.iterdir()): + if not child.is_dir() or child.name in SKIP_DIRS or child.name.startswith("."): + continue + if (child / "SKILL.md").exists() and child.name not in router_dirs: + errors.append( + f"directory '{child.name}' has SKILL.md but is not in router table" + ) + return errors @@ -72,6 +111,8 @@ def main() -> int: all_errors.extend(validate(skill_md, expected_name=child.name)) checked += 1 + all_errors.extend(check_router_consistency()) + if all_errors: print(f"Validated {checked} skill(s); found {len(all_errors)} issue(s):") for line in all_errors: