smart-donkey

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 93 Open GitHub ↗

All-in-one autonomous development workflow skill for Claude Code with self-learning capability

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Smart Donkey

An all-in-one autonomous development workflow skill for [Claude Code](https://claude.ai/claude-code) with self-learning capability.

Smart Donkey combines **requirements gathering**, **file-based planning**, **iterative execution**, and **post-session knowledge distillation** into a single unified workflow — and gets smarter with every session.

**[中文说明](#中文说明) | English**

## Why Smart Donkey?

Most AI coding workflows have gaps:
- **No requirements phase** — jump straight to code, build the wrong thing
- **No structured planning** — lose track in complex tasks
- **No error memory** — repeat the same mistakes across sessions
- **No learning** — start from scratch every time

Smart Donkey fixes all four. It's a donkey that carries your project load step by step, and **remembers which paths are steep**.

## Features

| Feature | Description |
|---------|-------------|
| **Requirements Gathering** | Interactive Q&A to clarify scope before coding |
| **File-Based Planning** | Persistent `task_plan.md`, `findings.md`, `progress.md` |
| **Adaptive Scaling** | Tiny tasks skip planning; big tasks get full workflow |
| **Iterative Execution** | Build-test-fix loops with 3-Strike Error Protocol |
| **Self-Learning Brain** | `smart-donkey-brain.md` accumulates distilled lessons |
| **Session Recovery** | Detects and resumes from previous unfinished work |
| **Bilingual** | Works in English and Chinese, matches user language |

## Installation

### Via Claude Code Plugin System (Recommended)

```bash
# Step 1: Add the repository as a marketplace
claude plugin marketplace add cloudyview/smart-donkey

# Step 2: Install the plugin
claude plugin install smart-donkey
```

### Manual Installation

Copy the skill directories into your Claude Code skills directory:

```bash
# Clone the repo first
git clone https://github.com/cloudyview/smart-donkey.git /tmp/smart-donkey

# Global (all projects)
cp -r /tmp/smart-donkey/skills/* ~/.claude/skills/

# Or project-local
cp -r /tmp/smart-donkey/skills/* .claude/skills/
```

This creates the correct structure Claude Code expects:
```
~/.claude/skills/smart-donkey/SKILL.md
~/.claude/skills/smart-donkey-status/SKILL.md
~/.claude/skills/smart-donkey-learn/SKILL.md
```

## Usage

### Start a Development Task

```
/smart-donkey Implement a user authentication system
```

Smart Donkey will:
1. Ask clarifying questions about the feature
2. Create a structured task plan
3. Execute phase by phase, verifying after each step
4. Distill lessons learned into the brain file

### Check Status

```
/smart-donkey-status
```

Shows a dashboard of current plan progress, blockers, and brain stats.

### Trigger Learning

```
/smart-donkey-learn
```

Explicitly distill lessons from the current session into `smart-donkey-brain.md`.

## The Self-Learning Loop

```
Session 1: Work -> Make mistakes -> Learn -> Save to brain
Session 2: Read brain -> Avoid old mistakes -> Learn new -> Update brain
Session N: Accumulated wisdom -> Faster work -> Fewer errors
```

The brain file (`smart-donkey-brain.md`) is a living document that:
- Stays under 200 lines (forced curation)
- Contains only reusable, cross-session lessons
- Gets read at the start of every session
- Gets pruned when entries become outdated

## Files Created

Smart Donkey creates these files in your **project root** (not in the skill directory):

| File | Purpose | Created When |
|------|---------|-------------|
| `task_plan.md` | Phase tracking, decisions, errors | Medium+ tasks |
| `findings.md` | Research, codebase analysis | Medium+ tasks |
| `progress.md` | Session log, actions taken | Medium+ tasks |
| `smart-donkey-brain.md` | Accumulated lessons across sessions | After learning phase |
| `docs/requirements/*.md` | Feature requirements | Complex features |

## Workflow Phases

```
Phase 1: UNDERSTAND  ->  Phase 2: PLAN  ->  Phase 3: EXECUTE  ->  Phase 4: VERIFY  ->  Phase 5: LEARN
   (Requirements)        (Task Plan)       (Dev Loop)          (Test & Fix)        (Distill)
```

Each phase scales to task size:

| Task Size | Example | Requirements | Planning | Learning |
|-----------|---------|-------------|----------|----------|
| Tiny | "rename this variable" | Skip | Skip | Skip |
| Small | "add input validation" | 1 question | Mental | Optional |
| Medium | "implement feature X" | 2-3 questions | File-based | Yes |
| Large | "build subsystem X" | Full gathering | Detailed plan | Yes |

## Configuration

Smart Donkey works out of the box with no configuration. The brain file and planning files are created as needed in your project directory.

### Customization

You can pre-create a `smart-donkey-brain.md` in your project root to seed initial knowledge:

```markdown
# Smart Donkey Brain
> Updated: 2024-01-01 | Sessions: 0

## User Preferences
- Always use TypeScript strict mode
- Prefer functional style over classes
- Run tests after every change

## Codebase Patterns
- Monorepo with pnpm workspaces
- Tests in __tests__/ directories using Vitest
```

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT License. See [LICENSE](LICENSE).

---

# 中文说明

**Smart Donkey（聪明驴）** 是一个为 [Claude Code](https://claude.ai/claude-code) 打造的一体化自主开发工作流技能，具备**自我学习**能力。

它将 **需求收集**、**文件化规划**、**迭代执行** 和 **会话后知识蒸馏** 融合为一个统一的工作流 —— 并且每次使用都会变得更聪明。

## 为什么叫 Smart Donkey？

驴子固执、有条理、从不放弃，一步一步驮着重物前行。
Smart Donkey 更进一步：它**记住每一次走过的路**，哪条路陡、哪里有坑，下次自动避开。

大多数 AI 编程工作流都有缺陷：
- **没有需求阶段** —— 直接写代码，结果做错方向
- **没有结构化规划** —— 复杂任务容易迷失
- **没有错误记忆** —— 跨会话重复犯同样的错
- **没有学习能力** —— 每次都从零开始

Smart Donkey 一次性解决这四个问题。

## 功能特性

| 功能 | 说明 |
|------|------|
| **需求收集** | 交互式问答，编码前先搞清楚范围 |
| **文件化规划** | 持久化的 `task_plan.md`、`findings.md`、`progress.md` |
| **自适应缩放** | 小任务跳过规划；大任务走完整流程 |
| **迭代执行** | 构建-测试-修复循环，配合三振出局错误协议 |
| **自学习大脑** | `smart-donkey-brain.md` 跨会话积累蒸馏知识 |
| **会话恢复** | 自动检测并恢复之前未完成的工作 |
| **双语支持** | 自动匹配用户语言（中文/英文） |

## 安装

### 通过 Claude Code 插件系统安装（推荐）

```bash
# 第一步：添加仓库为 marketplace
claude plugin marketplace add cloudyview/smart-donkey

# 第二步：安装插件
claude plugin install smart-donkey
```

### 手动安装

将 skill 目录复制到 Claude Code 的 skills 目录：

```bash
# 先克隆仓库
git clone https://github.com/cloudyview/smart-donkey.git /tmp/smart-donkey

# 全局安装（所有项目可用）
cp -r /tmp/smart-donkey/skills/* ~/.claude/skills/

# 或项目级安装
cp -r /tmp/smart-donkey/skills/* .claude/skills/
```

这会创建 Claude Code 要求的正确结构：
```
~/.claude/skills/smart-donkey/SKILL.md
~/.claude/skills/smart-donkey-status/SKILL.md
~/.claude/skills/smart-donkey-learn/SKILL.md
```

## 使用方法

### 启动开发任务

```
/smart-donkey 实现用户认证系统
```

Smart Donkey 会：
1. 提出澄清问题，确认需求
2. 创建结构化任务计划
3. 逐阶段执行，每步验证
4. 将学到的经验蒸馏到大脑文件

### 查看状态

```
/smart-donkey-status
```

显示当前计划进度、阻塞项和大脑统计的仪表盘。

### 触发学习

```
/smart-donkey-learn
```

手动触发蒸馏，将本次会话的经验提取到 `smart-donkey-brain.md`。

## 自学习循环

```
第 1 次会话：工作 -> 犯错 -> 学习 -> 保存到大脑
第 2 次会话：读取大脑 -> 避开旧错误 -> 学新知识 -> 更新大脑
第 N 次会话：积累的智慧 -> 更快完成 -> 更少出错
```

大脑文件 (`smart-donkey-brain.md`) 是一个活文档：
- 保持在 **200 行以内**（强制精炼，只留最有价值的）
- 只包含**跨会话可复用**的经验
- 每次会话开始时自动读取
- 过时的条目会被自动清理

## 工作流阶段

```
阶段 1: 理解需求  ->  阶段 2: 制定计划  ->  阶段 3: 迭代执行  ->  阶段 4: 验证测试  ->  阶段 5: 蒸馏学习
```

每个阶段根据任务规模自动伸缩：

| 任务规模 | 举例 | 需求收集 | 规划 | 学习 |
|---------|------|---------|------|------|
| 微型 | "把变量名改成驼峰" | 跳过 | 跳过 | 跳过 |
| 小型 | "加个输入验证" | 1 个问题 | 心算 | 可选 |
| 中型 | "实现功能 X" | 2-3 个问题 | 文件化 | 是 |
| 大型 | "构建子系统 X" | 完整收集 | 详细计划 | 是 |

## 创建的文件

Smart Donkey 在**项目根目录**创建以下文件（不在技能目录中）：

| 文件 | 用途 | 何时创建 |
|------|------|---------|
| `task_plan.md` | 阶段追踪、决策记录、错误日志 | 中型及以上任务 |
| `findings.md` | 研究发现、代码库分析 | 中型及以上任务 |
| `progress.md` | 会话日志、操作记录 | 中型及以上任务 |
| `smart-donkey-brain.md` | 跨会话积累的蒸馏知识 | 学习阶段后 |
| `docs/requirements/*.md` | 功能需求文档 | 复杂功能 |

## 自定义

可以在项目根目录预先创建 `smart-donkey-brain.md` 来注入初始知识：

```markdown
# Smart Donkey Brain
> Updated: 2024-01-01 | Sessions: 0

## User Preferences
- 始终使用 TypeScript strict mode
- 偏好函数式风格
- 每次修改后都要跑测试

## Codebase Patterns
- pnpm workspaces monorepo
- 测试在 __tests__/ 目录，使用 Vitest
```

## 贡献

欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可

MIT License。详见 [LICENSE](LICENSE)。

smart-donkey

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README