名称： Joan 工作流
描述： 当用户询问关于 "joan"、"pods"、"workspace"、"domain knowledge"、"context sync"、"joan init"、"joan todo"，或需要了解 Joan 知识管理系统如何运作的指导时，应使用此技能。提供关于 pods、todos、plans 和 workspace 管理的工作流指导。
版本： 0.1.0

Joan 工作流

Joan 是一个基于工作区的、用于 AI 辅助开发的知识与任务管理系统。本技能涵盖何时及如何使用 Joan 的核心概念。

核心概念

工作区

工作区是 Joan 中的顶级组织单元。每个工作区包含：
- Pods: 版本化的领域知识文档
- Todos: 限定于该工作区的任务
- Plans: 与任务关联的实现规范
- Members: 具有角色（管理员、成员）的团队成员

Pods

Pods 是包含领域知识的版本化 Markdown 文档。使用 Pods 来：
- 记录项目架构和设计决策
- 存储领域特定的术语和业务规则
- 在团队成员和 AI 助手之间共享知识
- 维护随着项目演进而更新的活文档

Pod 生命周期：
1. 使用 joan pod create 在本地创建
2. 在 .joan/pods/ 目录下编辑 Markdown 文件
3. 使用 joan pod push 推送到服务器
4. 使用 joan pod pull 拉取最新版本

Todos

Todos 是限定于某个工作区的任务。使用 Todos 来：
- 跟踪团队成员的工作项
- 分配任务并设置优先级
- 将实现计划与任务关联

Todo 工作流：
1. 使用 joan todo create 创建
2. 使用 joan todo list 列出
3. 随着工作进展更新状态
4. 完成后归档

Plans

Plans 是与 Todos 关联的实现规范。使用 Plans 来：
- 记录功能将如何实现
- 将复杂任务分解为步骤
- 与团队共享实现方法

CLI 命令参考

项目初始化

joan init                    # 交互式选择工作区
joan init -w <workspace-id>  # 非交互式，指定特定工作区
joan status                  # 显示项目和认证状态

Pod 管理

joan pod list               # 列出已跟踪的 pods
joan pod list --all         # 列出工作区中的所有 pods
joan pod add                # 将工作区中的 pods 添加到项目
joan pod create             # 在本地创建新 pod
joan pod pull               # 从服务器拉取 pods
joan pod push               # 将本地 pods 推送到服务器
joan pod open               # 在浏览器中打开 pod

Todo 管理

joan todo list              # 列出已跟踪 pods 相关的 todos
joan todo list --mine       # 列出分配给我的 todos
joan todo create            # 创建新 todo
joan todo update <id>       # 更新 todo 字段
joan todo archive <id>      # 归档已完成的 todo

Plan 管理

joan plan list <todo-id>    # 列出某个 todo 的 plans
joan plan create <todo-id>  # 创建实现计划
joan plan pull <todo-id>    # 从服务器拉取 plans
joan plan push <todo-id>    # 将 plans 推送到服务器

上下文生成

joan context claude         # 生成包含 Joan 上下文的 CLAUDE.md 文件

何时使用何种功能

开始新项目

1. 运行 joan init 将项目连接到工作区
2. 选择与项目领域相关的 pods
3. 运行 joan context claude 将上下文注入 CLAUDE.md
4. 在编码前阅读生成的 pod 引用

编码新功能前

1. 检查相关 pods 是否存在：joan pod list --all
2. 添加任何缺失的 pods：joan pod add
3. 拉取最新版本：joan pod pull
4. 阅读 pods 以理解领域上下文

完成工作后

1. 考虑是否应将新知识创建为 pod
2. 更新或创建 todos 以反映进展
3. 推送任何本地更改：joan pod push 和 joan todo push

记录新知识

1. 创建 pod：joan pod create
2. 在 Markdown 中编写领域知识
3. 推送以共享：joan pod push
4. 更新 CLAUDE.md 上下文：joan context claude

MCP 集成

Joan 在 https://joan.land/mcp/joan 提供了一个 MCP 服务器，包含以下工具：
- list_workspaces - 列出可访问的工作区
- list_pods - 列出工作区中的 pods
- get_pod - 获取 pod 内容

MCP 服务器使用 OAuth 2.1 认证。请先通过 CLI 使用 joan auth login 进行认证。

项目配置

Joan 将项目配置存储在 .joan/config.yaml 中：

workspace_id: <uuid>
tracked_pods:
  - name: "Pod 名称"
    id: <uuid>

Pods 在本地以 Markdown 文件形式存储在 .joan/pods/ 目录下。

最佳实践

Pod 编写

• 使用清晰、描述性的标题
• 包含知识适用的上下文信息
• 保持 pod 专注于单个领域概念
• 知识演进时及时更新 pods
• 在有用时引用相关的 pods

Todo 管理

• 以适当的粒度创建 todos（既不太大，也不太小）
• 将 todos 与相关 pods 关联以提供上下文
• 及时更新状态以保持团队信息同步
• 归档已完成的 todos 以减少干扰

上下文同步

• 更改已跟踪的 pods 后运行 joan context claude
• 在开始重要工作前拉取 pods
• 及时推送更改以与团队共享