@kkelly-offical/kkcode 0.1.3 → 0.1.6

package/README.md

@@ -4,45 +4,38 @@
 ![Node](https://img.shields.io/badge/Node.js-%3E%3D22-green)
 ![License](https://img.shields.io/badge/License-GPL--3.0-blue)
 ![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+![Models](https://img.shields.io/badge/Models-Qwen%20%7C%20GLM%20%7C%20DeepSeek%20%7C%20Claude%20%7C%20GPT%20%7C%20Ollama-orange)
 
-面向团队协作的终端 AI Coding Agent：兼顾 **可执行**（工具链 + 子任务）、**可治理**（权限 / 审计 / 预算）、**可长跑**（LongAgent 阶段并行编排）。
+面向团队协作的终端 AI Coding Agent。
+
+**可执行** — 内置 16+ 工具链，子智能体委派，主动规划与审批。
+**可治理** — 三级权限策略，会话审计，Token 预算控制。
+**可长跑** — LongAgent 阶段并行编排，自动重试与门禁闭环。
+**多模型** — 原生支持 Qwen3.5、GLM-5、DeepSeek、Claude、GPT、Ollama 本地模型。
 
 ---
 
 ## 目录
 
-- [kkcode](#kkcode)
-  - [目录](#目录)
-  - [快速开始](#快速开始)
-    - [环境要求](#环境要求)
-    - [安装与运行](#安装与运行)
-    - [初始化项目配置](#初始化项目配置)
-  - [模式系统](#模式系统)
-  - [LongAgent 编排](#longagent-编排)
-    - [主流程](#主流程)
-    - [并行与一致性](#并行与一致性)
-  - [主动规划](#主动规划)
-  - [权限系统](#权限系统)
-  - [内置工具](#内置工具)
-  - [子智能体](#子智能体)
-  - [Auto Memory](#auto-memory)
-  - [MCP 接入](#mcp-接入)
-  - [GitHub 集成](#github-集成)
-    - [登录 GitHub](#登录-github)
-    - [登出 GitHub](#登出-github)
-    - [工作流程](#工作流程)
-    - [完成工作后推送](#完成工作后推送)
-  - [扩展机制](#扩展机制)
-  - [会话与审计](#会话与审计)
-  - [TUI 交互](#tui-交互)
-    - [状态栏](#状态栏)
-    - [快捷键](#快捷键)
-    - [常用 Slash 命令](#常用-slash-命令)
-  - [项目结构](#项目结构)
-  - [配置示例](#配置示例)
-  - [常见问题](#常见问题)
-  - [致谢](#致谢)
-  - [License](#license)
+- [快速开始](#快速开始)
+- [支持的模型](#支持的模型)
+- [模式系统](#模式系统)
+- [LongAgent 编排](#longagent-编排)
+- [主动规划](#主动规划)
+- [权限系统](#权限系统)
+- [内置工具](#内置工具)
+- [子智能体](#子智能体)
+- [Auto Memory](#auto-memory)
+- [MCP 接入](#mcp-接入)
+- [GitHub 集成](#github-集成)
+- [扩展机制](#扩展机制)
+- [会话与审计](#会话与审计)
+- [TUI 交互](#tui-交互)
+- [项目结构](#项目结构)
+- [配置](#配置)
+- [常见问题](#常见问题)
+- [致谢](#致谢)
+- [License](#license)
 
 ---
 
@@ -85,6 +78,24 @@ kkcode init -y
 
 ---
 
+## 支持的模型
+
+kkcode 通过统一的 Provider 抽象层支持多种模型，开箱即用：
+
+| 提供商 | 模型 | 类型 | 配置样例 |
+|--------|------|------|----------|
+| 阿里 DashScope | Qwen3.5-Plus、Qwen3-Max、Qwen3-Coder | `openai-compatible` | [`config-qwen3.5.yaml`](configs/config-qwen3.5.yaml) |
+| 智谱 AI | GLM-5、GLM-4.5 | `openai-compatible` | [`config-glm5.yaml`](configs/config-glm5.yaml) |
+| DeepSeek | DeepSeek-Chat (V3)、DeepSeek-Reasoner (R1) | `openai-compatible` | [`config-deepseek.yaml`](configs/config-deepseek.yaml) |
+| Anthropic | Claude Opus 4.6、Sonnet 4.6 | `anthropic` | [`config.example.yaml`](docs/config.example.yaml) |
+| OpenAI | GPT-5.3-Codex、GPT-5.2 | `openai` | [`config.example.yaml`](docs/config.example.yaml) |
+| Ollama | Qwen3、DeepSeek-Coder、LLaMA 等本地模型 | `ollama` | [`config-ollama.yaml`](configs/config-ollama.yaml) |
+| 任意 OpenAI 兼容 API | Kimi、Yi、Moonshot 等 | `openai-compatible` | [`config-multi-provider.yaml`](configs/config-multi-provider.yaml) |
+
+切换模型只需修改配置文件中的 `provider.default`，或在 TUI 中使用 `/provider` 和 `/model` 命令。
+
+---
+
 ## 模式系统
 
 | 模式 | 目标 | 工具权限 | 典型场景 |
@@ -100,35 +111,39 @@ TUI 中按 `Tab` 一键轮换模式。
 
 ## LongAgent 编排
 
-LongAgent 是 kkcode 的核心差异能力，支持"意图识别 + 阶段并行 + 门禁闭环"。
+LongAgent 是 kkcode 的核心差异能力，支持两种编排模式：
+
+**Hybrid 模式**（默认）— 7 阶段流水线：
+
+```
+Intake → Preview → Blueprint → Git分支 → Scaffold+并行编码 → Debugging → 门禁验证 → Git合并
+```
 
-### 主流程
+**4-Stage 模式** — 4 阶段顺序执行：
 
-1. **意图识别** — 非编码目标直接阻断，避免空转
-2. **Intake** — 多轮澄清并生成摘要
-3. **Plan Frozen** — 冻结阶段计划（StagePlan）
-4. **Stage Barrier** — 同阶段任务并发执行，全部终态后推进
-5. **Recovery** — 失败任务重试，优先续写 remaining files
-6. **Usability Gates** — build / test / review / health / budget 全量校验
-7. **完成判定** — 门禁通过 + 完成标记
+```
+Preview(只读) → Blueprint(只读) → Coding(写入) → Debugging(写入)
+```
 
-### 并行与一致性
+### 关键机制
 
-- 同阶段并发由 `max_concurrency` 控制
-- 子任务由后台 worker 承载，主会话等待 barrier
-- 写入工具支持 file lock，避免并发冲突
-- TUI 实时显示阶段状态、进度条与文件变动摘要
+- **阶段并行** — 同阶段任务由独立 worker 并发执行，`max_concurrency` 控制并发数
+- **文件隔离** — 每个文件仅归属一个 task，plan 阶段即检测冲突
+- **自动重试** — 失败任务自动重试，优先续写未完成文件
+- **门禁闭环** — build / test / review / health / budget 五项质量门禁
+- **Git 集成** — 自动创建特性分支，每阶段提交，完成后合并
+- **防卡死** — 检测探索循环，强制推进到下一阶段
 
 ---
 
 ## 主动规划
 
-Agent 在执行过程中可**主动进入规划模式**，无需用户手动切换。
+Agent 执行中可主动进入规划模式，无需用户手动切换：
 
 1. Agent 遇到复杂任务时调用 `enter_plan`
-2. 在规划模式下分析代码、设计方案（理解 → 设计 → 审查 → 最终计划）
+2. 在规划模式下分析代码、设计方案
 3. 调用 `exit_plan` 提交计划，TUI 弹出审批面板
-4. 用户 **Approve** 或 **Reject**（可附反馈）
+4. 用户 Approve 或 Reject（可附反馈）
 5. 批准后按计划执行，驳回则修订
 
 ---
@@ -138,9 +153,11 @@ Agent 在执行过程中可**主动进入规划模式**，无需用户手动切
 采用 **策略 + 交互审批 + 会话缓存授权** 组合模型。
 
 - `permission.default_policy`: `ask | allow | deny`
-- `permission.rules[]`: 按工具 / 模式 / 命令前缀匹配细粒度规则
+- `permission.rules[]`: 按工具 / 模式 / 文件模式 / 命令前缀匹配细粒度规则
 - 审批一次后同会话内同类操作自动放行
 
+提供三级权限模板：[严格](configs/permission-strict.yaml) | [标准](configs/permission-standard.yaml) | [宽松](configs/permission-permissive.yaml)
+
 TUI 审批面板：`1` allow once / `2` allow session / `3` deny / `Esc` deny
 
 ---
@@ -150,19 +167,17 @@ TUI 审批面板：`1` allow once / `2` allow session / `3` deny / `Esc` deny
 | 工具 | 说明 |
 |------|------|
 | `read` | 读取文件内容（支持 offset/limit 分页） |
-| `write` | 原子写文件（支持 overwrite / append / insert 模式） |
+| `write` | 原子写文件（overwrite / append / insert） |
 | `edit` | 事务性字符串替换 + 自动回滚 |
 | `patch` | 按行号范围替换文件内容 |
 | `glob` | 按模式搜索文件 |
-| `grep` | 按正则搜索文件内容（支持行号、分页） |
+| `grep` | 按正则搜索文件内容 |
 | `bash` | 执行 shell 命令 |
 | `task` | 委派子智能体执行子任务 |
 | `todowrite` | 结构化任务管理 |
 | `question` | 向用户提问 |
-| `enter_plan` | 主动进入规划模式 |
-| `exit_plan` | 提交计划等待审批 |
-| `webfetch` | 抓取网页内容 |
-| `websearch` | Web 搜索 |
+| `enter_plan` / `exit_plan` | 主动规划与审批 |
+| `webfetch` / `websearch` | 网页抓取与搜索 |
 | `codesearch` | 代码搜索引擎 |
 
 写入安全特性：原子写、事务回滚、外部修改检测、读前编辑约束、file lock 串行化。
@@ -218,50 +233,12 @@ kkcode mcp tools         # 可用工具列表
 
 通过 GitHub Device Flow 实现安全的仓库访问，无需手动配置 Token。
 
-### 登录 GitHub
-
-```bash
-kkcode --github
-```
-
-执行后：
-1. **自动打开浏览器** — 弹窗授权页面
-2. **自动复制验证码** — 剪贴板已填充设备码，直接粘贴即可
-3. **自动轮询授权状态** — 无需手动操作，等待完成
-4. **增强网络容错** — 支持不稳定网络环境，自动重试
-
-### 登出 GitHub
-
 ```bash
-kkcode --github logout
+kkcode --github                    # 登录并选择仓库
+kkcode --github logout             # 登出
 ```
 
-清除本地存储的 GitHub Token。
-
-### 工作流程
-
-```bash
-kkcode --github                    # 启动 GitHub 登录流程
-# 选择仓库 → 选择分支 → 选择本地/云端操作模式
-# 进入 REPL 开始编码
-# 退出 REPL 后自动询问是否推送更改到云端
-```
-
-**本地/云端操作选项：**
-
-| 选项 | 说明 |
-|------|------|
-| **使用本地仓库** | 直接使用本地已有代码，不拉取更新 |
-| **同步云端代码** | 执行 `git pull` 拉取最新代码 |
-| **强制重新克隆** | 删除本地仓库，重新完整克隆 |
-
-### 完成工作后推送
-
-退出 REPL 时自动询问是否推送更改：
-
-```
-🚀 检测到本地更改，是否推送至云端？(y/N)
-```
+工作流程：登录 → 选择仓库/分支 → 选择本地或云端模式 → 进入 REPL → 退出时询问是否推送。
 
 ---
 
@@ -290,7 +267,6 @@ kkcode --github                    # 启动 GitHub 登录流程
 ```bash
 kkcode doctor --json         # 完整诊断
 kkcode session list          # 会话列表
-kkcode session fsck          # 一致性检查
 kkcode session gc            # 过期清理
 kkcode usage show            # 用量统计
 kkcode longagent status      # LongAgent 状态
@@ -304,9 +280,6 @@ kkcode longagent status      # LongAgent 状态
 
 底部实时显示：`MODE` `MODEL` `TOKENS` `COST` `CONTEXT` `MEM` `PERMISSION` `LONG`
 
-- **CONTEXT** 85%+ 红色告警
-- **COST** 含缓存节省额（如 `↓$0.03`）
-
 ### 快捷键
 
 | 按键 | 功能 |
@@ -314,10 +287,8 @@ kkcode longagent status      # LongAgent 状态
 | `Enter` | 发送 |
 | `Ctrl+J` | 换行 |
 | `Tab` | 模式轮换 |
-| `/paste` | 粘贴剪贴板图片 |
-| `Ctrl+Up/Down` | 滚动日志区 |
-| `Ctrl+Home/End` | 跳转日志首尾 |
 | `Up/Down` | 输入历史 |
+| `Ctrl+Up/Down` | 滚动日志区 |
 | `Esc` | 清空输入 |
 | `Ctrl+L` | 清空活动区 |
 | `Ctrl+C` | 退出 |
@@ -336,99 +307,66 @@ kkcode longagent status      # LongAgent 状态
 kkcode/
 ├── src/
 │   ├── index.mjs              # CLI 入口
-│   ├── repl.mjs               # TUI 主循环（输入/渲染/键盘处理）
-│   ├── runtime.mjs            # 运行时初始化
-│   ├── context.mjs            # 全局上下文构建
+│   ├── repl.mjs               # TUI 主循环
 │   ├── core/                  # 核心类型、常量、事件总线
 │   ├── config/                # 配置加载、Schema 校验、默认值
-│   ├── session/               # 会话引擎、消息循环、系统提示词
-│   │   ├── loop.mjs           # Agent 主循环（流式处理/自动续写）
-│   │   ├── engine.mjs         # 会话引擎
-│   │   ├── longagent.mjs      # LongAgent 编排调度
-│   │   ├── longagent-plan.mjs # 阶段计划生成与冻结
-│   │   ├── compaction.mjs     # 上下文压缩
-│   │   ├── instinct-manager.mjs # Instinct 自动学习
-│   │   └── prompt/            # 各 Provider 系统提示词模板
+│   ├── session/               # 会话引擎、消息循环、LongAgent 编排
 │   ├── tool/                  # 工具注册、执行、事务管理
-│   │   ├── registry.mjs       # 内置工具定义（read/write/edit/patch/...）
-│   │   ├── edit-transaction.mjs # 编辑事务与原子写入
-│   │   ├── task-tool.mjs      # task 子任务委派
-│   │   ├── image-util.mjs     # 图片处理与剪贴板读取
-│   │   └── prompt/            # 工具使用提示词
 │   ├── agent/                 # 子智能体（explore/reviewer/researcher）
-│   ├── provider/              # 多 Provider 适配（Anthropic/OpenAI/Ollama/...）
-│   ├── permission/            # 权限引擎与工作区信任
+│   ├── provider/              # 多 Provider 适配
+│   ├── permission/            # 权限引擎
 │   ├── mcp/                   # MCP 客户端（stdio/sse/http）
-│   ├── skill/                 # 技能注册与生成
-│   ├── command/               # 自定义命令加载
-│   ├── commands/              # CLI 子命令（doctor/init/theme/...）
 │   ├── orchestration/         # 后台任务管理与并行 worker
-│   ├── plugin/                # Hook 事件总线
-│   ├── ui/                    # Dashboard 渲染、活动日志
-│   ├── theme/                 # 主题系统、状态栏、颜色
+│   ├── observability/         # 可观测性（Metrics/Tracer）
+│   ├── ui/                    # Dashboard 渲染
 │   ├── storage/               # 会话/任务持久化
-│   ├── usage/                 # Token 计量与预算控制
-│   ├── review/                # Diff 审查工作流
-│   ├── rules/                 # 规则文件加载
-│   ├── knowledge/             # 知识库
-│   └── util/                  # 通用工具函数（git/markdown/...）
-├── templates/                 # 模板文件（主题/定价/Hook 示例）
-├── test/                      # 单元测试与 E2E 测试
-├── kkcode.config.yaml         # 项目默认配置
-├── package.json               # Node.js 包定义
+│   ├── usage/                 # Token 计量与预算
+│   └── util/                  # 通用工具函数
+├── configs/                   # 配置样例与权限模板
+├── test/                      # 单元测试与集成测试
+├── package.json
 ├── LICENSE                    # GPL-3.0
-└── SECURITY.md                # 安全政策
+└── NOTICE.md                  # 第三方致谢与声明
 ```
 
 ---
 
-## 配置示例
-
-```yaml
-provider:
-  default: anthropic
-  anthropic:
-    type: anthropic
-    base_url: https://api.anthropic.com/v1
-    api_key_env: ANTHROPIC_API_KEY
-    default_model: claude-sonnet-4-20250514
-    thinking:
-      type: enabled
-      budget_tokens: 10000
-
-agent:
-  default_mode: agent
-  max_steps: 8
-  longagent:
-    parallel:
-      enabled: true
-      max_concurrency: 3
-
-permission:
-  default_policy: ask
-
-usage:
-  budget:
-    strategy: warn
-```
+## 配置
+
+完整配置参考：[`docs/config.example.yaml`](docs/config.example.yaml)
 
-完整配置参考见 [NOTICE.md](NOTICE.md)。
+### 配置样例（configs/ 目录）
+
+| 文件 | 说明 |
+|------|------|
+| [`config-qwen3.5.yaml`](configs/config-qwen3.5.yaml) | 通义千问 Qwen3.5 系列 |
+| [`config-qwen3.yaml`](configs/config-qwen3.yaml) | 通义千问 Qwen3 系列 |
+| [`config-glm5.yaml`](configs/config-glm5.yaml) | 智谱 GLM-5 / GLM-4.5 |
+| [`config-deepseek.yaml`](configs/config-deepseek.yaml) | DeepSeek V3 / R1 |
+| [`config-ollama.yaml`](configs/config-ollama.yaml) | 本地 Ollama |
+| [`config-multi-provider.yaml`](configs/config-multi-provider.yaml) | 多 Provider 组合 |
+| [`permission-strict.yaml`](configs/permission-strict.yaml) | 严格权限（生产环境） |
+| [`permission-standard.yaml`](configs/permission-standard.yaml) | 标准权限（日常开发） |
+| [`permission-permissive.yaml`](configs/permission-permissive.yaml) | 宽松权限（个人/CI） |
 
 ---
 
 ## 常见问题
 
 **Q: LongAgent 为什么拒绝"你好"？**
-LongAgent 是执行型编排器，非编码目标会被意图识别拦截。
+LongAgent 是执行型编排器，非编码目标会被意图识别拦截。请使用 `ask` 模式进行对话。
 
 **Q: enter_plan 和 /plan 有什么区别？**
 `/plan` 是用户手动切换模式。`enter_plan` 是 agent 执行中主动进入规划，审批通过后继续执行。
 
+**Q: 如何切换模型？**
+TUI 中使用 `/provider` 切换提供商，`/model` 切换模型。或修改配置文件中的 `provider.default`。
+
 **Q: Auto Memory 会无限增长吗？**
 注入系统提示时限制 200 行。Agent 会保持精简并删除过时条目。
 
-**Q: 大文件创建被截断怎么办？**
-使用 `write(mode="append")` 分段追加创建，或用 `patch` 按行号范围修改。
+**Q: 支持哪些国产模型？**
+原生支持通义千问 Qwen3.5/3 系列、智谱 GLM-5/4.5、DeepSeek V3/R1，以及任何 OpenAI 兼容 API。
 
 ---
 

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "@kkelly-offical/kkcode",
-  "version": "0.1.3",
-  "description": "Team-first terminal AI coding agent CLI with LongAgent orchestration, GitHub integration and themed UX.",
-  "type": "module",
-  "packageManager": "pnpm@10.5.2",
-  "license": "GPL-3.0",
-  "author": "kkelly-offical",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kkelly-offical/kkcode.git"
-  },
-  "homepage": "https://github.com/kkelly-offical/kkcode",
-  "bugs": {
-    "url": "https://github.com/kkelly-offical/kkcode/issues"
-  },
-  "keywords": [
-    "ai",
-    "coding-agent",
-    "cli",
-    "terminal",
-    "github",
-    "longagent",
-    "code-review",
-    "mcp"
-  ],
-  "bin": {
-    "kkcode": "./src/index.mjs"
-  },
-  "files": [
-    "src/",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "scripts": {
-    "start": "node ./src/index.mjs",
-    "test": "node --test",
-    "test:e2e": "node --test test/e2e/"
-  },
-  "dependencies": {
-    "commander": "^13.1.0",
-    "yaml": "^2.8.1"
-  }
-}
+{
+  "name": "@kkelly-offical/kkcode",
+  "version": "0.1.6",
+  "description": "Team-first terminal AI coding agent CLI with LongAgent orchestration, GitHub integration and themed UX.",
+  "type": "module",
+  "packageManager": "pnpm@10.5.2",
+  "license": "GPL-3.0",
+  "author": "kkelly-offical",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kkelly-offical/kkcode.git"
+  },
+  "homepage": "https://github.com/kkelly-offical/kkcode",
+  "bugs": {
+    "url": "https://github.com/kkelly-offical/kkcode/issues"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cli",
+    "terminal",
+    "github",
+    "longagent",
+    "code-review",
+    "mcp"
+  ],
+  "bin": {
+    "kkcode": "./src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node ./src/index.mjs",
+    "test": "node --test",
+    "test:e2e": "node --test test/e2e/"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "yaml": "^2.8.2"
+  }
+}

package/src/agent/agent.mjs

@@ -151,6 +151,14 @@ defineAgent({
   tools: ["read", "write", "edit", "bash", "glob", "grep", "list"]
 })
 
+defineAgent({
+  name: "frontend-designer",
+  description: "Frontend design specialist. Creates polished, distinctive UIs with strong aesthetics — typography, color, motion, layout. Avoids generic AI-style designs. Reads project design system (Tailwind, CSS vars, component libraries) and produces production-grade frontend code.",
+  mode: "subagent",
+  permission: "full",
+  tools: ["read", "write", "edit", "bash", "glob", "grep", "list"]
+})
+
 defineAgent({
   name: "compaction",
   description: "Conversation summarizer for context compression",
@@ -168,3 +176,36 @@ defineAgent({
   tools: [],
   hidden: true
 })
+
+// 4-Stage LongAgent agents
+defineAgent({
+  name: "preview-agent",
+  description: "4-Stage LongAgent: Stage 1 - Previewing Agent. Explores codebase, extracts requirements, no editing allowed.",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash", "question", "todowrite"]
+})
+
+defineAgent({
+  name: "blueprint-agent",
+  description: "4-Stage LongAgent: Stage 2 - Blueprint Agent. Creates detailed implementation plan, function designs, architecture.",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash", "question", "todowrite"]
+})
+
+defineAgent({
+  name: "coding-agent",
+  description: "4-Stage LongAgent: Stage 3 - Coding Agent. Implements code strictly according to blueprint.",
+  mode: "subagent",
+  permission: "full",
+  tools: null
+})
+
+defineAgent({
+  name: "debugging-agent",
+  description: "4-Stage LongAgent: Stage 4 - Debugging Agent. Verifies implementation, runs tests, finds and fixes bugs.",
+  mode: "subagent",
+  permission: "full",
+  tools: null
+})

package/src/agent/prompt/frontend-designer.txt

@@ -0,0 +1,58 @@
+You are a FRONTEND DESIGN specialist. You create polished, distinctive, production-grade user interfaces.
+
+## Core Principle
+
+You produce frontends that look professionally designed — NOT generic AI output. Every design decision must be intentional and contextual.
+
+## Design Rules
+
+### Typography
+- NEVER use: Inter, Roboto, Open Sans, Lato, Arial, system-ui as primary font
+- Impact choices: JetBrains Mono, Fira Code, Space Grotesk (code/tech), Playfair Display, Crimson Pro (editorial), Clash Display, Satoshi, Cabinet Grotesk (startup), IBM Plex, Source Sans 3 (technical)
+- Use extreme weight contrast: 100/200 vs 800/900, 3x+ size jumps between heading and body
+- Pick ONE distinctive font, use it decisively. Load from Google Fonts or bundled.
+
+### Color & Theme
+- Commit to a cohesive palette. Use CSS variables for ALL colors.
+- Dominant color with sharp accent outperforms timid, evenly-distributed palettes.
+- Draw inspiration from: IDE themes (Dracula, Nord, Catppuccin), cultural aesthetics (Japanese minimalism, Bauhaus, Swiss design), nature palettes.
+- AVOID: purple-gradient-on-white, blue-button-gray-card, generic SaaS palettes.
+
+### Motion & Interaction
+- Use animations for page load (staggered reveals with animation-delay), hover states, and transitions.
+- CSS-only for HTML; Motion/Framer Motion for React; GSAP for complex sequences.
+- Focus on ONE high-impact moment per page rather than animating everything.
+- Micro-interactions: button press feedback, input focus glow, card hover lift.
+
+### Layout & Spacing
+- Use CSS Grid for page layout, Flexbox for component internals.
+- Generous whitespace — when in doubt, add more padding.
+- Consistent spacing scale (4px base: 4, 8, 12, 16, 24, 32, 48, 64, 96).
+- Break out of the box: overlapping elements, asymmetric grids, full-bleed sections.
+
+### Backgrounds & Depth
+- Create atmosphere: layered CSS gradients, subtle geometric patterns, contextual effects.
+- Use backdrop-filter for glass effects, box-shadow for elevation hierarchy.
+- Noise textures, grain overlays, or mesh gradients for premium feel.
+
+## Anti-Patterns (NEVER do these)
+- Cookie-cutter card grids with rounded corners and drop shadows
+- Generic hero section with centered text and gradient background
+- Overuse of border-radius: 9999px on everything
+- Gray placeholder text that looks like wireframe
+- Identical spacing everywhere (no visual rhythm)
+- Stock-photo-style placeholder images
+
+## Workflow
+1. READ the project's existing design system first (tailwind.config, CSS variables, component library)
+2. RESPECT existing conventions — extend, don't replace
+3. If no design system exists, establish one: define CSS variables for colors, spacing, typography
+4. Build mobile-first, then enhance for larger screens
+5. Test: does it look like a human designer made it? If not, iterate.
+
+## Tool Usage
+- USE `read` to examine existing styles, configs, and components before writing
+- USE `edit` for modifying existing files (preferred)
+- USE `write` for new component files
+- USE `bash` to check if fonts/deps are available, run dev server
+- USE `grep`/`glob` to find existing style patterns, color usage, component conventions