Skip to content

cloudyview/smart-donkey

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
.claude-plugin
.claude-plugin
 
 
skills
skills
 
 
.gitignore
.gitignore
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

Smart Donkey

An all-in-one autonomous development workflow skill for 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)

# 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:

# 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:

# 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.

License

MIT License. See LICENSE.

中文说明

Smart Donkey（聪明驴） 是一个为 Claude Code 打造的一体化自主开发工作流技能，具备自我学习能力。

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

为什么叫 Smart Donkey？

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

大多数 AI 编程工作流都有缺陷：

  • 没有需求阶段 —— 直接写代码，结果做错方向
  • 没有结构化规划 —— 复杂任务容易迷失
  • 没有错误记忆 —— 跨会话重复犯同样的错
  • 没有学习能力 —— 每次都从零开始

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

功能特性

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

安装

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

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

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

手动安装

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

# 先克隆仓库
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 来注入初始知识：

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

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

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

贡献

欢迎贡献！请查看 CONTRIBUTING.md。

许可

MIT License。详见 LICENSE。

About

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

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors