mcpField
S
swain-roadmap

swain-roadmap

github.com/cristoslcAgent 工作流259 次安装25 周前更新
代码仓库

关于 swain-roadmap

swain-roadmap 是一项根据工件图重新生成项目路线图并打开结果的 skill。它支持项目级视图、指定工件的路线图切片，以及纯文本命令行摘要。

主要功能

  1. 01重新生成项目路线图
  2. 02生成指定范围的路线图切片
  3. 03呈现优先级与依赖关系
  4. 04从工件内容填充意图占位符
  5. 05显示命令行状态与路线图摘要

适用场景

  1. 01刷新项目路线图
  2. 02查看某个愿景或计划的路线图切片
  3. 03在终端查看优先级与依赖关系

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cristoslc/swain --skill swain-roadmap

安装后在 Claude Code 中输入/swain-roadmap确认已加载。

详细介绍

路线图

在执行任何会改变状态的操作之前，检查是否存在活动会话：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null

如果 JSON 输出中的 "status" 不是 "active"，请告知操作员：“没有活动会话——要用 /swain-init 启动一个吗？”如果操作员选择忽略，则继续。

根据制品图重新生成 ROADMAP.md 并打开它。繁重工作由 swain-design 中的 chart.sh roadmap 完成——此技能是面向用户的入口。

调用时

1. 定位 chart.sh
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
CHART_SH="$REPO_ROOT/.agents/bin/chart.sh"

如果未找到 chart.sh，请告知用户未安装 swain-design，然后停止。

2. 重新生成路线图

解析参数：如果用户提供了制品 ID（例如，swain-roadmap VISION-001），则将该 ID 设为 SCOPE_ID。否则，SCOPE_ID 为空。

如果设置了 SCOPE_ID：

bash "$CHART_SH" roadmap --scope "$SCOPE_ID"

这会在指定制品的文件夹中写入一个 roadmap.md。

如果 SCOPE_ID 为空：

bash "$CHART_SH" roadmap

这会在项目根目录中写入 ROADMAP.md，并重新生成各自制品文件夹中所有按 Vision 和 Initiative 划分的 roadmap.md 切片。

项目级 ROADMAP.md 包含：

  • 象限图 — 以 PNG 格式呈现的优先级矩阵（如果 mmdc 不可用，则回退为内嵌 Mermaid）
  • 图例 — 按象限分组并附带短 ID 的史诗
  • 艾森豪威尔表格 — 立即执行 / 安排 / 进行中 / 待办，包含进度、解除阻塞的计数和需要操作员决策的事项
  • 甘特时间线 — 按优先级错开的计划及依赖关系链接
  • 依赖关系图 — 跨优先级边界的阻塞关系（仅在存在依赖关系时显示）

每个制品切片包含：意图摘要、带链接和进度的子制品表、汇总进度条、近期 git 提交，以及艾森豪威尔优先级子集。

2.5. 后处理意图占位符

chart.sh 完成后，扫描输出文件中的 {{INTENT: <ID>}} 占位符。对每个占位符：

  1. 读取源制品 Markdown 文件。
  2. 提取 ## Value Proposition（适用于 Visions）或 ## Goal / Objective（适用于 Initiatives）中的第一句话。
  3. 将 {{INTENT: <ID>}} 标记替换为提取的句子。
  4. 写回文件。

如果找不到该章节，则保留占位符原样（操作员可以手动填写，也可以等待通过 SPEC-144 填充 brief-description frontmatter）。

3. 打开路线图

如果设置了 SCOPE_ID，则打开对应的切片。根据图缓存查找制品的文件路径，以找到其文件夹：

ARTIFACT_FILE="$(bash "$CHART_SH" show "$SCOPE_ID" 2>/dev/null | grep -oE 'docs/[^ ]+' | head -1)"
if [ -n "$ARTIFACT_FILE" ]; then
    open "$REPO_ROOT/$(dirname "$ARTIFACT_FILE")/roadmap.md"
fi

如果未指定范围，则打开项目级路线图：

open "$REPO_ROOT/ROADMAP.md"

始终打开渲染后的文件，以便操作员查看完整的图表和示意图。不要让操作员自己打开——直接打开即可。

4. 显示 CLI 摘要

ROADMAP.md 包含表格、Mermaid 图表和图片引用，这些内容无法在终端中渲染。使用 --cli 标志获取预先格式化的纯文本摘要：

bash "$CHART_SH" roadmap --cli

这会输出一个确定且对齐的摘要，按艾森豪威尔象限（立即执行、安排、进行中、待办）分组，并将所有第一层子项（EPIC、SPEC、SPIKE）嵌套在其父级 Initiative 下。直接显示此输出——不要重新格式化或筛选。

在 CLI 输出前说“ROADMAP.md 已刷新并打开。”对于指定范围的运行，则改说“{SCOPE_ID} 的路线图切片已刷新并打开。”

上下文丰富的显示

列出路线图条目（艾森豪威尔象限、甘特时间线）时，将每个制品显示为上下文行，而不是单独显示 ID：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/artifact-context.sh" <ID> 2>/dev/null

如果该工具不可用，则回退为 <ID> — <title>。

6. 关注泳道上下文

如果 .agents/session.json 中设置了关注泳道，请在末尾提及。

FOCUS="$(bash "$REPO_ROOT/.agents/bin/swain-focus.sh" 2>/dev/null)"

如果设置了关注项，请注明：“关注：{FOCUS}。建议仅针对该泳道。”

新鲜度检查（供其他技能使用）

其他技能可以直接调用 chart.sh，根据过时情况重新生成内容。此技能始终无条件重新生成——这是“强制刷新”路径。

状态仪表板（ADR-023，原名 SPEC-122）

当操作人员说“状态”“接下来做什么”“仪表板”“概览”“进展如何”或“我应该做什么”时，运行状态脚本：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
STATUS_SCRIPT="$REPO_ROOT/.agents/bin/swain-status.sh"
[ -f "$STATUS_SCRIPT" ] && bash "$STATUS_SCRIPT" --refresh || echo "status dashboard script not found"

紧凑模式（MOTD）：bash "$STATUS_SCRIPT" --compact

缓存

状态会写入 .agents/status-cache.json，有效期为 120 秒。使用 --refresh 绕过缓存，使用 --json 获取原始输出。

建议

从 JSON 缓存中读取 .priority.recommendations[0]。设置了焦点泳道时，建议会限定在该愿景／计划范围内。

模式推断
  1. 两份规格都在审查中，且有待处理的战略决策 -> 询问操作人员
  2. 规格等待审查 -> 详细模式
  3. 已设置焦点泳道，且有待处理的决策 -> 愿景模式
  4. 没有可采取行动的事项 -> 愿景模式（主计划镜像）
待决策事项（路线图集成）

使用 chart.sh roadmap --json 进行艾森豪威尔分类。显示“立即处理”和“安排处理”象限中需要操作人员决策的前 5 项。

错误处理

  • 如果 chart.sh 失败，显示错误输出，并建议运行 swain-doctor
  • 如果 ROADMAP.md 存在但 chart.sh 不可用，显示现有文件（可能已过时），并发出过时警告
  • 绝不要直接失败——显示所有可用内容

评论

支持 Markdown