" [--draft] [--desc] # 创建任务（--draft 占位） /kanban run <task_id> # 运行完整 FSM 流程 /kanban status # 查看看板 /kanban show <task_id> # 查看任务详情 /kanban inbox analyze <task_id> # 分析 inbox 需求 /kanban inbox add <task_id> "<text>" # 添加反馈 /kanban task promote <task_id> # draft → 正式流程 /kanban knowledge search <kw> [--domain] # 搜索知识库 /kanban knowledge conflicts --task-id <id> # 检测方案冲突 /kanban decide <task_id> --action <action> # 用户决策 /kanban recover [<task_id>] # 崩溃恢复 /kanban dashboard start # 启动 Dashboard /kanban version list # 查看版本历史 ``` ## Roadmap - [ ] 跨仓库任务编排（多 repo 联动） - [ ] Web Dashboard（脱离终端的独立 UI） - [ ] 更多 LLM 引擎支持（Gemini、GPT 等） - [ ] 任务模板市场（预设常见任务类型） - [ ] 团队协作模式（多人共享看板） ## 项目结构 ``` .claude/skills/kanban/ SKILL.md # 命令路由和 Agent 调度规范 agents/ # Agent 定义 (10 个 Agent) rules/ # 框架规则 (17 条铁律) references/ # 命令参考文档（按需加载） versions/ # 版本记录与 CHANGELOG core/ # Python 核心库 (cli/ + domain/ + infra/，Python 3.9+) templates/ # 配置和报告模板 test/ # 测试套件 (358 tests) .kanban/ # 运行时数据（init 后生成） config.json # 项目配置（含 python_bin） workflow.json # FSM 定义 test_profile.md # 测试与验收规范（自然语言） knowledge/ # 结构化知识库 (entries/*.json + index.json) tasks/TASK-NNN/ # 任务数据 + iteration-N/ 产物 + inbox.md archive/ # 已归档任务 ``` ## 文档详细文档在 [docs/](docs/) 目录，包含技术提案、需求分析和竞品调研报告。 ## License MIT </article></body></html>

# Kanban Framework [![GitHub stars](https://img.shields.io/github/stars/kongshan001/kanban-framework?style=social)](https://github.com/kongshan001/kanban-framework) [![GitHub issues](https://img.shields.io/github/issues/kongshan001/kanban-framework)](https://github.com/kongshan001/kanban-framework/issues) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green)](https://claude.ai/code) [![Tests](https://img.shields.io/badge/tests-358%20passed-brightgreen)](https://github.com/kongshan001/kanban-framework/actions/workflows/test-coverage.yml) [![Version](https://img.shields.io/badge/version-v0.13.0-blue)](.claude/skills/kanban/versions/CHANGELOG.md) [🇨🇳 中文 README](#kanban-framework) 基于 FSM 的多 Agent 任务编排框架，为 Claude Code 提供标准化的 Plan / Execute / Evaluate / Archive 全流程自动化。 **一句话**: 把「需求分析 -> 编码 -> 多角色评审 -> 自迭代改进」串成一条流水线，让 AI 写代码也有代码评审和质量门禁。 ## vs 纯对话式 AI 写代码 | | 纯对话 | Kanban Framework | |---|---|---| | 代码质量 | 靠运气 | 4 角色评审门禁 | | 迭代改进 | 手动提要求 | 自动不达标迭代 | | 任务管理 | 靠脑记 | 可视化看板 | | 进度追踪 | 无 | 实时任务状态 | ## 30 秒上手 ```bash # 安装 npx skills add kongshan001/kanban-framework -a claude-code # 在任意项目中初始化 /kanban init # 创建任务并运行 /kanban create "贪吃蛇游戏" /kanban run TASK-001 ``` 框架自动完成: 规划需求 → Plan Review 审核 → QA 产出测试用例 → Spec Review 审核 → 分配 Agent 并行编码 → 4 角色并行评审 → 复盘总结 → 等你确认后归档。你只需在最后执行: ``` /kanban decide TASK-001 --action approve_and_archive ``` ## 功能亮点 ### 三层 Guard 防护 ``` 阶段转换 Guard -- 禁止跳跃，Plan 不完成不能进 Execute 产物完整性 Guard -- 每个阶段必须有文档产出，缺一则阻断评分标准 Guard -- 10 分制统一标准，未达阈值强制迭代 ``` 任何一个 Guard 拦截都会输出 `GUARD BLOCKED: {reason}`，问题可追溯。 ### 全流程质量门禁 10 阶段 FSM 流程，在传统 Plan-Execute-Evaluate 之外增加： | 阶段 | 内容 | |------|------| | Plan Review | 6 维度量化审核需求分析质量 | | QA Spec | QA 产出测试用例文档（单元/边界/集成） | | Spec Review | 5 维度审核测试用例文档质量 | | Retrospective | 强制复盘总结 + 知识结构化提取 | | Draft | 占位任务，通过 inbox 逐步完善需求后 promote 进入正式流程 | ### 多角色并行评估全部 agent 使用 `kanban-` 前缀命名，可通过 `workflow.json` 灵活配置。 | 角色 | 审核维度 | |------|---------| | kanban-code-reviewer | 架构、代码质量、安全、测试覆盖 | | kanban-qa | 测试完整性、边界覆盖、错误处理、用例对齐 | | kanban-pm | 需求覆盖、用户体验、功能完整性 | | kanban-designer | API 设计、模块结构、可扩展性 | 所有角色并行启动（`run_in_background`），评估速度不线性增长。 ### 自迭代闭环评估不达标时自动进入迭代: - **Hot iteration**: 评分 >= 7.0 且无架构问题，从 Execute 阶段快速修复 - **Full iteration**: 存在架构问题，从 Plan 阶段重新规划 - 最多 6 轮迭代，超限后交由用户决策 ### Init 智能扫描 `/kanban init` 自动分析项目环境： - 检测项目已有的 agent/skills，与 kanban 默认 agent 智能合并 - 检测语言/框架基础设施（pytest、pylint、ESLint、Jest 等），缺失时建议补充 - 检测 superpowers 必装 skill（brainstorming/writing-plans/TDD），未安装时警告 - 游戏项目检测 GM 指令系统等专项基建 - 自动生成 `.kanban/test_profile.md`（测试规范 + 验收流程，自然语言可编辑） ### 测试规范定制（test_profile.md） `kanban init` 自动生成自然语言测试规范文件，Executor 和 QA Agent 按项目实际情况执行： - 定义测试框架、文件命名、运行命令 - 描述验收流程（如启动游戏、发送 GM 指令、检查 UI） - 声明需要的测试 Skills（如 Playwright、pytest） - 完全自由格式，无 JSON 配置负担 ### 知识系统结构化知识库替代扁平 markdown，支持领域分类、相似 pitfalls 预警、自动过期： - Plan 阶段自动注入相关历史经验 - Execute 阶段踩坑预警（检测相似历史条目） - Archive 阶段自动提取新知识条目 - 方案冲突检测：知识库有多个方案时，Plan 阶段暂停让用户选择 ### Inbox 需求收集 + Draft 占位任务支持「先占位、再完善」的任务创建模式： - `/kanban create "暂定名" --draft` 创建占位任务，跳过 brainstorming - 通过 inbox.md 用自然语言逐步补充需求 - `/kanban inbox analyze ` 分析 inbox → 提取需求 → 判断 FSM 入口 → 补入 spec.md - `/kanban task promote ` 将 draft 推进到正式 FSM 流程 ### Git Worktree 隔离每个任务在独立 worktree 中开发，与主干完全隔离: ``` .kanban/tasks/TASK-NNN/worktree/ # 任务的独立工作区 ``` - 代码变更不影响主干 - 归档时合并，用户确认后才生效 - 清理后不留残留 ### 软链部署，一处更新处处同步 ``` .claude/agents/planner.md -> ../../.claude/skills/kanban/agents/planner.md .claude/rules/test-with-code.md -> ../../.claude/skills/kanban/rules/test-with-code.md ``` 框架源文件更新后，所有项目的 Agent 和 Rule 自动同步，无需重新 init。 ### Skills 全自动演化任务归档时自动从 `execution_pitfalls.md` 和 `execution_decisions.md` 中提取框架改进点: 1. **Extract** -- 按分类（agent/rule/lib）生成候选改进 JSON 2. **Apply** -- agent/rule 类改进自动写入源文件并同步 3. **Report** -- 生成 `skills_evolution_report.json` 存档框架越用越好，无需人工维护 prompt。 ### 知识沉淀每次迭代的经验教训自动结构化存储到 `.kanban/knowledge/entries/`（JSON 格式），支持按领域、标签、任务检索。Knowledge Manager Agent 在归档阶段自动提取，踩坑经验不再重复。 ### Agent 体系 #### 内置 Agent 框架内置 10 个 Agent，覆盖完整的任务生命周期: | Agent | 负责阶段 | 职责 | |-------|---------|------| | planner | Plan | 需求分析、知识注入、方案冲突检测、编写 spec.md 和 task_breakdown.json | | plan-reviewer | Plan Review | 6 维度量化审核需求分析质量 | | qa | QA Spec | 产出测试用例文档（单元/边界/集成） | | test-spec-reviewer | Spec Review | 5 维度审核测试用例文档 | | executor | Execute | TDD 编码、踩坑预警、产出 TDD 证据和执行报告 | | code_reviewer | Evaluate | 审核架构设计、代码质量、安全性和测试覆盖率 | | qa (eval) | Evaluate | 按 test_profile.md 逐条执行验收流程 | | pm | Evaluate | 验证需求覆盖、用户体验、功能完整性 | | designer | Evaluate | 评审 API 设计、模块结构、可扩展性和一致性 | | knowledge-manager | Retrospective | 提取经验教训、编写复盘文档、沉淀结构化知识条目 | #### 自定义 Agent 评估角色可通过 `workflow.json` 的 `agents` 数组添加自定义 agent: ```json { "agents": [ { "role": "security_auditor", "name": "Security Auditor", "phases": ["evaluate"], "description": "专注安全审计，检查依赖漏洞、敏感数据泄露等", "scores": ["dependency_security", "data_leakage", "auth_bypass"] } ] } ``` 添加后，框架在 Evaluate 阶段自动调度自定义 agent 并行评估，产出 `{role}_report.json`。评分维度、调度方式与内置角色一致。 #### Phase-Agent-Product 概览 | 阶段 | 调度 Agent | 产出文件 | |------|-----------|---------| | Plan | planner | `spec.md`, `plan.md`, `task_breakdown.json` | | Plan Review | plan-reviewer | `plan_review_report.json` | | QA Spec | qa | `test_spec.md` | | Spec Review | test-spec-reviewer | `spec_review_report.json` | | Execute | executor | 源代码, TDD 证据, `execution_summary/pitfalls/decisions.md` | | Evaluate | code_reviewer, qa, pm, designer (+ 自定义) | `{role}_report.json` (每角色一份) | | Retrospective | knowledge-manager | `retrospective.md`, `acceptance.md`, 知识条目 | | User Decision | (等待用户操作) | -- | | Archive | orchestrator | 归档目录, git merge | ## 架构 ### FSM 流程图 ```mermaid stateDiagram-v2 [*] --> Plan: /kanban run TASK-NNN state Plan { [*] --> AnalyzeRequirements: Planner Agent AnalyzeRequirements --> CreateBreakdown CreateBreakdown --> [*]: requirements.md + task_breakdown.json } Plan --> Execute: Guard PASS (artifacts complete) state Execute { [*] --> RunSubtasks: Executor Agent RunSubtasks --> WriteTests WriteTests --> CommitCode CommitCode --> [*]: execution_summary.md + pitfalls + decisions } Execute --> Evaluate: Guard PASS (artifacts complete) state Evaluate { [*] --> ParallelReview: 4 Agents (run_in_background) ParallelReview --> CollectScores: code_reviewer + qa + pm + designer CollectScores --> [*]: 4 *_report.json } Evaluate --> Retrospective: Guard PASS (scores valid) state Retrospective { [*] --> ReadPitfalls: Knowledge Manager Agent ReadPitfalls --> ExtractLessons ExtractLessons --> WriteKnowledgeLog WriteKnowledgeLog --> [*]: retrospective.md } Retrospective --> UserDecision: Guard PASS state UserDecision { [*] --> WaitForUser WaitForUser --> [*]: /kanban decide } UserDecision --> Archive: approve_and_archive state Archive { [*] --> InboxCheck: Guard Layer 6 InboxCheck --> MergeWorktree MergeWorktree --> CleanupWorktree CleanupWorktree --> [*]: task moved to archive/ } Archive --> [*]: Done %% Self-iteration paths Evaluate --> Execute: Hot iteration (score >= 7, no arch issues) Evaluate --> Plan: Full iteration (score < 7 or arch issues) ``` ### 阶段产物与参与 Agent | 阶段 | 参与 Agent | 产出文件 | |------|-----------|---------| | Plan | Planner | `requirements.md`, `task_breakdown.json` | | Execute | Executor | 源代码, `execution_summary.md`, `execution_pitfalls.md`, `execution_decisions.md` | | Evaluate | Code Reviewer, QA, PM, Designer | `code_reviewer_report.json`, `qa_report.json`, `pm_report.json`, `designer_report.json` | | Retrospective | Knowledge Manager | `retrospective.md`, `knowledge-log.md` | | Archive | Orchestrator | 归档目录, git merge | ### 自迭代路径 ``` +-----------+ | pending | +-----+-----+ | v +-----+-----+ +--->| Plan |<-----------------+ | +-----+-----+ | | | | | v | | +-----+-----+ Full | | | Execute |<--- iteration -----+ | +-----+-----+ (score < 7) | | | | v | | +-----+-----+ | | | Evaluate | | | +-----+-----+ | | | | | +-----+-----+ | | | Self-Check |--- Hot iteration -+ | +-----+-----+ (score >= 7) | | all_pass / max_reached | v | +-----+-----+ | | User | | | Decision | | +-----+-----+ | | approve | v | +-----+-----+ +----| Archive | restart_from_plan + +------------+ ``` ## 竞品对比 | 特性 | Kanban Framework | 原生 Claude Code Agent | Cursor Rules | Claude Code Hooks | |------|-----------------|----------------------|-------------|------------------| | 任务生命周期管理 | FSM 全流程 | 无 | 无 | 无 | | 质量门禁 (Guard) | 三层防护 | 无 | 无 | 事件拦截 | | 多角色评估 | 可配置多角色并行 | 无 | 无 | 无 | | 自迭代闭环 | Hot/Full 自动 | 无 | 无 | 无 | | 代码隔离 | Git Worktree | 无 | 无 | 无 | | 可视化 Dashboard | 内置 | 无 | 无 | 无 | | 框架自演化 | 全自动 | 无 | 无 | 无 | | 知识沉淀 | 内置 knowledge-log | 无 | 无 | 无 | | 集成方式 | Claude Code 原生 | 内置 | IDE 内置 | 内置 | | 学习成本 | 5 个命令 | 低 | 极低 | 中 | **核心差异**: 原生 Agent 和 Cursor Rules 提供「能力」，Kanban 提供「流程」。流程保证质量，能力只保证速度。 ## 常见场景 ### 单人复杂任务一个需要多文件协作的功能（比如完整游戏、数据管线），交给 Kanban 自动拆解、编码、评审: ``` /kanban create "实现一个扫雷游戏，含 UI 和逻辑" /kanban run TASK-002 ``` ### 多任务并行项目多个独立功能并行开发，互不干扰: ``` /kanban create "用户认证模块" # TASK-003 /kanban create "数据导出功能" # TASK-004 /kanban run TASK-003 & /kanban run TASK-004 & ``` 每个任务在独立 worktree 中执行，评估通过后逐个归档合并。 ### 框架自身迭代框架自身的增强也走 Kanban 流程（铁律 IR-12）: ``` /kanban create "优化 Planner 的需求分析 prompt" /kanban run TASK-005 ``` Skills 演化机制会在每次归档后自动提取改进点，越用越智能。 ## 安装方式 ### 方式 1: npx skills add (推荐) ```bash npx skills add kongshan001/kanban-framework -a claude-code ``` ### 方式 2: git clone ```bash git clone https://github.com/kongshan001/kanban-framework.git # 手动将 .claude/skills/kanban/ 复制到项目的 .claude/skills/ ``` ### 方式 3: Claude Code Plugin ```bash claude plugin install https://github.com/kongshan001/kanban-framework ``` 安装后在项目中运行 `/kanban init` 即可完成初始化（创建目录结构、安装 agents/rules/dashboard）。 ## 命令速查 ``` /kanban init # 初始化 /kanban create "" [--draft] [--desc] # 创建任务（--draft 占位） /kanban run <task_id> # 运行完整 FSM 流程 /kanban status # 查看看板 /kanban show <task_id> # 查看任务详情 /kanban inbox analyze <task_id> # 分析 inbox 需求 /kanban inbox add <task_id> "<text>" # 添加反馈 /kanban task promote <task_id> # draft → 正式流程 /kanban knowledge search <kw> [--domain] # 搜索知识库 /kanban knowledge conflicts --task-id <id> # 检测方案冲突 /kanban decide <task_id> --action <action> # 用户决策 /kanban recover [<task_id>] # 崩溃恢复 /kanban dashboard start # 启动 Dashboard /kanban version list # 查看版本历史 ``` ## Roadmap - [ ] 跨仓库任务编排（多 repo 联动） - [ ] Web Dashboard（脱离终端的独立 UI） - [ ] 更多 LLM 引擎支持（Gemini、GPT 等） - [ ] 任务模板市场（预设常见任务类型） - [ ] 团队协作模式（多人共享看板） ## 项目结构 ``` .claude/skills/kanban/ SKILL.md # 命令路由和 Agent 调度规范 agents/ # Agent 定义 (10 个 Agent) rules/ # 框架规则 (17 条铁律) references/ # 命令参考文档（按需加载） versions/ # 版本记录与 CHANGELOG core/ # Python 核心库 (cli/ + domain/ + infra/，Python 3.9+) templates/ # 配置和报告模板 test/ # 测试套件 (358 tests) .kanban/ # 运行时数据（init 后生成） config.json # 项目配置（含 python_bin） workflow.json # FSM 定义 test_profile.md # 测试与验收规范（自然语言） knowledge/ # 结构化知识库 (entries/*.json + index.json) tasks/TASK-NNN/ # 任务数据 + iteration-N/ 产物 + inbox.md archive/ # 已归档任务 ``` ## 文档详细文档在 [docs/](docs/) 目录，包含技术提案、需求分析和竞品调研报告。 ## License MIT </article></body></html>

kanban

Installation

SKILL.md