knowy-cli 0.1.2

package/README.md

@@ -0,0 +1,138 @@
+# Knowy
+
+[繁體中文](README.zh-TW.md)
+
+**Give your AI a structured project brain.**
+
+Your AI assistant sees your code — but does it understand *why* you built it this way? What principles you won't compromise on? What you already tried and learned from?
+
+Knowy gives your project three structured knowledge files that any AI tool can read, turning scattered context into a shared understanding.
+
+## Quick Start
+
+```bash
+npx knowy-cli init
+```
+
+This creates a `.knowledge/` directory in your project and connects it to your AI tools. Then, in your AI tool (e.g., Claude Code):
+
+```
+/knowy init
+```
+
+This starts an interactive conversation to help you fill in your knowledge files.
+
+## What It Creates
+
+```
+.knowledge/
+  principles.md         ← Core beliefs and rules (rarely changes)
+  vision.md             ← Goals, architecture, roadmap (evolves)
+  experience.md         ← Distilled lessons (grows over time)
+  research/             ← Exploratory notes → may become principles
+  design/               ← Detailed designs → inform vision
+  history/              ← Event records → distilled into experience
+  .templates/           ← Reference templates (managed by Knowy)
+```
+
+## How It Works
+
+Every project has knowledge that lives in people's heads — why certain decisions were made, what failed before, where things are headed. Knowy makes that knowledge explicit and structured:
+
+- **Principles** answer "what rules guide us?" — your non-negotiable beliefs and the rules derived from them.
+- **Vision** answers "where are we going?" — the problem you're solving, current state, and roadmap.
+- **Experience** answers "what have we learned?" — patterns from development, especially where expectations met reality.
+
+Your AI tools read these files automatically, so their suggestions align with your project's actual context — not just the code.
+
+## Skills
+
+Knowy installs four skills for Claude Code (under the `/knowy` namespace):
+
+| Skill | What it does |
+|-------|-------------|
+| `/knowy init` | Interactive conversation to create or populate knowledge files |
+| `/knowy update` | Check knowledge file structure against latest templates |
+| `/knowy judge` | Cross-check the three files for consistency and coherence |
+| `/knowy next` | Plan the next step based on your principles, vision, and experience |
+
+### `/knowy judge` — Knowledge Health Check
+
+Runs 17 checks across your knowledge files:
+
+- **Self-consistency** (3): Are derivation chains intact? Is the structure sound?
+- **Internal coherence** (3): Are there contradictions within each file?
+- **Cross-references** (6): Do the files agree with each other? Checks all six directions (e.g., "Does experience support the vision?" is different from "Does vision address what experience found?")
+- **Project alignment** (3): Do the files match the actual project state (code, dependencies, git history)?
+- **Overall** (1): Synthesis — where should you focus?
+- **Beyond scope** (1): Is there content that belongs elsewhere?
+
+Results use traffic light indicators: 🟢 healthy (one-line summary), 🟡 tension (expanded with details), 🔴 conflict (expanded with suggested action).
+
+## Supported Tools
+
+Knowy detects and connects to 25+ AI and spec tools:
+
+| Category | Tools |
+|----------|-------|
+| **AI Coding** | Claude Code, Cursor, Windsurf, GitHub Copilot, Codex CLI, Gemini CLI, Kiro, Amazon Q, Cline, Roo Code, Kilo Code, Aider, Continue.dev, Augment Code, Amp, Devin, Warp, Zed, OpenCode, Qodo, JetBrains AI, Tabnine, Replit Agent, Bolt.new |
+| **Spec Tools** | Speckit, OpenSpec, Kiro Specs |
+| **Standard** | AGENTS.md (cross-tool standard) |
+
+`knowy init` auto-detects which tools you have and injects a reference to your `.knowledge/` files. `knowy update` catches tools added later.
+
+## MCP Server
+
+Knowy also works as an MCP (Model Context Protocol) server, so your AI tool can use Knowy directly without the CLI:
+
+```bash
+npx knowy-cli setup-mcp
+```
+
+This configures the MCP server for your AI tool (Claude Code, Claude Desktop, Cursor, etc.). Once set up, your AI can call `knowy_init`, `knowy_update`, `knowy_judge`, and `knowy_next` as native tools.
+
+You can also configure it manually. Add to your AI tool's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "knowy": {
+      "command": "npx",
+      "args": ["-y", "knowy-cli", "--", "knowy-mcp"]
+    }
+  }
+}
+```
+
+## Updating
+
+When Knowy releases a new version with improved skills or templates:
+
+```bash
+npx knowy-cli update
+```
+
+This updates skills and templates (managed files) without touching your knowledge files. It also detects any new AI tools you've added since the last run.
+
+## Design Principles
+
+- **Tool-agnostic**: `.knowledge/` is plain Markdown — works with any tool, or none.
+- **Zero dependencies**: No runtime, no server. Three Markdown files and a few skills.
+- **No lock-in**: Knowy doesn't own your workflow. It connects to your existing tools, not the other way around.
+- **Progressive adoption**: Use just the files, or add the skills, or both.
+
+## The Theory (for the curious)
+
+The three-file structure isn't arbitrary. It maps to the structure of a *judgment* — the minimal unit of knowledge:
+
+- **Principles** = what is correct (the standard)
+- **Vision** = what is being built (the construction)
+- **Experience** = what context we're in (the situation)
+
+These three perspectives are inseparable — each one only makes sense in relation to the other two. `/knowy judge` verifies that they're still in alignment, and `/knowy next` uses all three to plan coherent next steps.
+
+This framework draws from [triperspectivalism](https://en.wikipedia.org/wiki/Triperspectivalism) and type-theoretic judgments (Γ ⊢ t : A). If you're curious, the research papers behind Knowy's design are in the project's `.knowledge/research/` directory.
+
+## License
+
+MIT

package/README.zh-TW.md

@@ -0,0 +1,138 @@
+# Knowy
+
+[English](README.md)
+
+**給你的 AI 一個結構化的專案大腦。**
+
+你的 AI 助手看得到你的程式碼——但它理解你*為什麼*這樣設計嗎？哪些原則是你不會妥協的？哪些你已經試過、從中學到教訓了？
+
+Knowy 為你的專案建立三份結構化的知識文件，讓任何 AI 工具都能讀取，把散落的脈絡變成共享的理解。
+
+## 快速開始
+
+```bash
+npx knowy-cli init
+```
+
+這會在你的專案中建立 `.knowledge/` 目錄並連結你的 AI 工具。接著，在你的 AI 工具中（例如 Claude Code）：
+
+```
+/knowy init
+```
+
+這會啟動一段互動式對話，幫助你填寫知識文件。
+
+## 建立的結構
+
+```
+.knowledge/
+  principles.md         ← 核心信念和規則（很少變動）
+  vision.md             ← 目標、架構、路線圖（持續演進）
+  experience.md         ← 蒸餾出的教訓（逐漸成長）
+  research/             ← 探索性筆記 → 可能成為原則
+  design/               ← 詳細設計 → 反映到願景
+  history/              ← 事件記錄 → 蒸餾成經驗
+  .templates/           ← 參考模板（由 Knowy 管理）
+```
+
+## 運作方式
+
+每個專案都有活在人們腦中的知識——為什麼做出某些決定、什麼曾經失敗、接下來要往哪裡走。Knowy 把這些知識變得明確且結構化：
+
+- **原則（Principles）** 回答「什麼規則引導我們？」——你不可妥協的信念，以及從中推導出的規則。
+- **願景（Vision）** 回答「我們要往哪裡走？」——要解決的問題、現狀和路線圖。
+- **經驗（Experience）** 回答「我們學到了什麼？」——開發中的模式，特別是預期和現實有落差的地方。
+
+你的 AI 工具會自動讀取這些文件，讓它的建議能符合專案的實際脈絡——而不只是程式碼。
+
+## Skills
+
+Knowy 為 Claude Code 安裝四個 skill（在 `/knowy` 命名空間下）：
+
+| Skill | 功能 |
+|-------|------|
+| `/knowy init` | 互動式對話，建立或填寫知識文件 |
+| `/knowy update` | 檢查知識文件結構是否符合最新模板 |
+| `/knowy judge` | 交叉檢查三份文件的一致性和連貫性 |
+| `/knowy next` | 根據原則、願景和經驗規劃下一步 |
+
+### `/knowy judge` — 知識健康檢查
+
+對你的知識文件執行 17 項檢查：
+
+- **自洽性**（3）：推導鏈是否完整？結構是否健全？
+- **內部一致**（3）：各文件內部是否有矛盾？
+- **交叉引用**（6）：三份文件之間是否一致？檢查所有六個方向（例如「經驗是否支持願景？」和「願景是否回應了經驗的發現？」是不同的問題）
+- **專案對齊**（3）：文件是否與專案實際狀態一致（程式碼、依賴、git 歷史）？
+- **總體**（1）：綜合歸納——應該先關注哪裡？
+- **超出範圍**（1）：有沒有不屬於這個專案的內容？
+
+結果使用交通燈指示：🟢 健康（一行摘要）、🟡 張力（展開細節）、🔴 衝突（展開並建議行動）。
+
+## 支援的工具
+
+Knowy 偵測並連結 25+ 種 AI 和規格工具：
+
+| 類別 | 工具 |
+|------|------|
+| **AI 編碼** | Claude Code、Cursor、Windsurf、GitHub Copilot、Codex CLI、Gemini CLI、Kiro、Amazon Q、Cline、Roo Code、Kilo Code、Aider、Continue.dev、Augment Code、Amp、Devin、Warp、Zed、OpenCode、Qodo、JetBrains AI、Tabnine、Replit Agent、Bolt.new |
+| **規格工具** | Speckit、OpenSpec、Kiro Specs |
+| **標準** | AGENTS.md（跨工具標準） |
+
+`knowy init` 自動偵測你安裝了哪些工具，並注入指向 `.knowledge/` 的引用。`knowy update` 會補上之後新增的工具。
+
+## MCP Server
+
+Knowy 也可以作為 MCP（Model Context Protocol）server 運作，讓你的 AI 工具直接使用 Knowy，不需要 CLI：
+
+```bash
+npx knowy-cli setup-mcp
+```
+
+這會為你的 AI 工具（Claude Code、Claude Desktop、Cursor 等）設定 MCP server。設定完成後，你的 AI 可以直接呼叫 `knowy_init`、`knowy_update`、`knowy_judge` 和 `knowy_next`。
+
+也可以手動設定。在你的 AI 工具的 MCP 設定中加入：
+
+```json
+{
+  "mcpServers": {
+    "knowy": {
+      "command": "npx",
+      "args": ["-y", "knowy-cli", "--", "knowy-mcp"]
+    }
+  }
+}
+```
+
+## 更新
+
+當 Knowy 發布新版本（改進的 skills 或模板）：
+
+```bash
+npx knowy-cli update
+```
+
+這會更新 skills 和模板（受管理的文件），不會動到你的知識文件。它也會偵測你在上次執行後新增的 AI 工具。
+
+## 設計原則
+
+- **工具無關**：`.knowledge/` 是純 Markdown——任何工具都能用，或不用工具也行。
+- **零依賴**：不需要 runtime，不需要 server。三份 Markdown 文件和幾個 skills。
+- **不鎖定**：Knowy 不擁有你的工作流程。它連結到你現有的工具，而不是反過來。
+- **漸進採用**：只用文件，或加上 skills，或兩者都用。
+
+## 理論基礎（給好奇的人）
+
+三份文件的結構不是隨意的。它對應到 *判斷（judgment）* 的結構——知識的最小單位：
+
+- **原則** = 什麼是正確的（規範）
+- **願景** = 正在建造什麼（構造）
+- **經驗** = 我們所處的脈絡（處境）
+
+這三個視角不可分割——每一個都只有在與另外兩個的關係中才有意義。`/knowy judge` 驗證它們是否仍然對齊，`/knowy next` 利用三者來規劃連貫的下一步。
+
+這個框架源自[三視角主義（triperspectivalism）](https://en.wikipedia.org/wiki/Triperspectivalism)和型別論中的判斷（Γ ⊢ t : A）。如果你有興趣，Knowy 設計背後的研究文件在專案的 `.knowledge/research/` 目錄中。
+
+## 授權
+
+MIT

package/bin/knowy-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { startMcpServer } from '../src/mcp-server.js';
+startMcpServer();

package/bin/knowy.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "knowy-cli",
+  "version": "0.1.2",
+  "description": "Give your AI a structured project brain",
+  "type": "module",
+  "bin": {
+    "knowy": "./bin/knowy.js",
+    "knowy-mcp": "./bin/knowy-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "skills/",
+    "snippets/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "knowledge",
+    "development",
+    "methodology",
+    "claude",
+    "cursor",
+    "copilot",
+    "agents"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timcsy/knowy"
+  }
+}

package/skills/knowy-init/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: knowy-init
+description: AI-guided creation of project knowledge files (.knowledge/)
+user-invokable: true
+argument-hint: "[topic or file to focus on]"
+---
+
+# Knowy Init
+
+Help the user create or populate their project knowledge files through layered, progressive conversation.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Governance Principles
+
+- **Principles are the highest authority.** When helping write principles, push the user to find the *root* — the one belief everything else derives from. Don't settle for surface-level rules.
+- **Vision evolves with understanding.** It's OK if vision is incomplete at first. Help the user capture what they know now.
+- **Experience is distilled, not accumulated.** Guide the user to extract patterns, not dump event logs.
+- **Knowledge files are indexes, not encyclopedias.** Keep core files short. Point to subdirectories for details.
+- **Never write files without explicit user confirmation.** Always show the draft first.
+
+## Workflow
+
+### 1. Read current state
+
+- Read `.knowledge/principles.md`, `.knowledge/vision.md`, `.knowledge/experience.md`
+- Read `.knowledge/.templates/` to understand suggested structure
+- Read project structure, package.json/Cargo.toml/etc. to understand the tech context
+- Identify which files are empty or still contain only template comments
+
+### 2. Determine scope
+
+- If `$ARGUMENTS` specifies a file (e.g., "principles"): focus on that file
+- If `$ARGUMENTS` specifies a subdirectory file (e.g., "design/auth-system"): help create that file
+- If `$ARGUMENTS` is empty: assess all three core files and start with whichever needs the most work
+
+### 3. Progressive conversation
+
+Use layered questioning — start broad, then drill deeper. Don't ask all questions at once.
+
+**For principles.md — Layer by layer:**
+
+Layer 1 (Root):
+- "What problem does this project exist to solve?"
+- "If you could only keep one rule about how this project works, what would it be?"
+- "What would you *never* compromise on, even under deadline pressure?"
+
+Layer 2 (Derive):
+- "Why is that true? What deeper belief makes you hold that rule?"
+- "If that's your root axiom, what follows from it? What rules does it imply?"
+- "Can you think of a time this principle was tested? What happened?"
+
+Layer 3 (Structure):
+- "Let's trace the derivation chain: [root axiom] → [principle 1] → [specific rule]. Does this chain make sense?"
+- "Are there principles that reinforce each other? How do they connect?"
+- "Is there anything you believe that *doesn't* derive from your root axiom? That might be a second axiom, or it might derive from the first in a way we haven't found yet."
+
+**For vision.md — Layer by layer:**
+
+Layer 1 (Problem):
+- "Who has the problem this project solves? What do they do today without your project?"
+- "What's the core idea — in one or two sentences?"
+
+Layer 2 (State):
+- "What works right now? What's broken or missing?"
+- "What are the key technical decisions you've made, and why?"
+
+Layer 3 (Direction):
+- "What are the next 2-3 milestones? What does each one deliver?"
+- "For each milestone: what must be done before it? How will you know it's done?"
+- "Is there anything in the roadmap you're uncertain about? Let's mark that explicitly."
+
+**For experience.md — Layer by layer:**
+
+Layer 1 (Surface):
+- "What surprised you during development?"
+- "What took longer than expected? Why?"
+- "What would you warn your past self about?"
+
+Layer 2 (Pattern):
+- "Is there a pattern behind those surprises? Something that might happen again?"
+- "What did you expect would happen vs what actually happened?"
+- "How did you solve it? Would you solve it the same way again?"
+
+Layer 3 (Distill):
+- "Let's turn that into a lesson: what's the one-sentence pattern?"
+- "What theory or assumption was wrong? What's the corrected understanding?"
+- "Where in the codebase can we see the evidence of this lesson?"
+
+**For subdirectory files (research/, design/, history/):**
+- Read existing core files for context
+- Ask about the specific topic
+- Suggest a filename following the directory's purpose
+- After creating: suggest how the content might eventually distill into the parent core file
+
+### 4. Draft content
+
+Based on the conversation:
+- Draft the content in the user's language
+- Follow the structure from the templates but use real content
+- For principles: show explicit derivation chains (Root Axiom → Principle → What it means in practice)
+- For vision: be concrete about current state, include success criteria for milestones
+- For experience: use the four-part format (Theory said X → Actually happened Y → We solved it by Z → Lesson: W)
+
+### 5. Self-check before proposing
+
+Before showing the draft to the user, verify:
+- **Self-consistency**: Does the draft contradict itself?
+- **Cross-consistency**: Does the draft conflict with the other two knowledge files?
+- **Project alignment**: Does the draft match the actual project state?
+
+If you find issues, revise the draft or flag them to the user.
+
+### 6. Confirm and write
+
+- Present the draft to the user
+- Highlight any concerns from the self-check
+- Ask for feedback and iterate if needed
+- Only write to files after explicit user confirmation
+- Never overwrite existing content without showing a diff of what will change
+
+## Guidelines
+
+- **Language**: Read `.knowy.json` → `language` field (e.g., `"zh-TW"`). Use that language for ALL output — questions, drafts, suggestions, everything. If `.knowy.json` is missing or has no language field, detect from conversation context or default to English.
+- **Layer your questions** — don't dump all questions at once. Ask 2-3, listen, then go deeper.
+- Keep language practical and clear — avoid academic jargon
+- Reference existing content in other knowledge files when relevant
+- If the user seems unsure, offer concrete examples from common project types
+- For subdirectory files, suggest how content might eventually be distilled into core files
+- Push for specificity — "write clean code" is not a principle; "every function has exactly one responsibility because [root axiom]" is