plans-kanban

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 任务跟踪要求：执行任何工作流或技能步骤之前，必须为所有步骤创建或更新任务跟踪，并随进度变化保持同步。
• 用户问题提示意味着要直接在 Codex 中询问用户。
• 出现 Claude 专用的模式切换说明时，请忽略。
• 严格执行约定：用户明确调用技能时，必须按原样执行该技能协议。
• 子 Agent 授权：当用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行每个列出的子技能步骤，并逐步报告证据。
• 如果所需步骤或工具无法在此环境中运行，请停止并在调整方案前询问用户。

Codex 项目参考资料加载（无钩子）

Codex 不会接收基于 Claude 钩子的文档注入。 进行编码、规划、调试、测试或审查时，请按照此路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目特定路径、命令、模块及工作流/测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

根据情况阅读的文档：

• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规格/测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件选择的领域文档

不要盲目阅读所有文档。先从 docs-index-reference.md 开始，然后仅打开与任务相关的文件。

快速摘要

**目标：**用于查看计划目录的可视化仪表板服务，支持进度跟踪和时间线可视化。

工作流：

1. 启动服务 — 使用 CLI 选项指定计划目录
2. 浏览仪表板 — 查看包含进度条、阶段状态和活动热力图的计划卡片
3. 检查计划 — 查看甘特图样式的时间线、优先级指示器以及问题/分支链接

关键规则：

• 首次使用前需要运行 npm install（gray-matter）
• 使用 $kanban 斜杠命令快速访问
• 扫描包含 plan.md 文件的目录

保持审慎。运用批判性思维和顺序思维。每项断言都必须有可追溯的证据和置信度百分比（想法应高于 80%）。

plans-kanban

支持进度跟踪和时间线可视化的计划仪表板服务。

⚠️ 需要安装

**此技能需要 npm 依赖项。**运行以下任一命令：

# Option 1: Install via ClaudeKit CLI (recommended)
ck init  # Runs install.sh which handles all skills

# Option 2: Manual installation
cd .claude/skills/plans-kanban
npm install

依赖项：gray-matter

如果未安装，查看计划详情时会出现 Error 500。

用途

用于查看计划目录的可视化仪表板，提供：

• 每个计划的进度跟踪
• 时间线/甘特图可视化
• 阶段状态指示器
• 活动热力图

快速开始

# View plans dashboard
node .claude/skills/plans-kanban/scripts/server.cjs \
  --dir ./plans \
  --open

# Explicit local host
node .claude/skills/plans-kanban/scripts/server.cjs \
  --dir ./plans \
  --host localhost \
  --open

# Background mode
node .claude/skills/plans-kanban/scripts/server.cjs \
  --dir ./plans \
  --background

# Stop all running servers
node .claude/skills/plans-kanban/scripts/server.cjs --stop

斜杠命令

使用 $kanban 快速访问：

$kanban plans/           # View plans dashboard
$kanban --stop           # Stop kanban server

功能

仪表板视图

• 带进度条的计划卡片
• 阶段状态分类（已完成、进行中、待处理）
• 最后修改时间戳
• 问题和分支链接
• 优先级指示器

时间线可视化

• 计划的甘特图样式时间线
• 时长跟踪
• 活动热力图

设计

• 带深色模式的玻璃拟态 UI
• 响应式网格布局
• 暖色强调色

CLI 选项

选项	说明	默认值
--dir <path>	计划目录	-
--port <number>	服务端口	3500
--host <addr>	绑定的主机	localhost
--open	自动打开浏览器	false
--background	在后台运行	false
--stop	停止所有服务	-

架构

scripts/
├── server.cjs               # Main entry point
└── lib/
    ├── port-finder.cjs      # Port allocation (3500-3550)
    ├── process-mgr.cjs      # PID management
    ├── http-server.cjs      # HTTP routing
    ├── plan-parser.cjs      # Plan.md parsing
    ├── plan-scanner.cjs     # Directory scanning
    ├── plan-metadata-extractor.cjs  # Rich metadata
    └── dashboard-renderer.cjs       # HTML generation

assets/
├── dashboard-template.html  # Dashboard HTML template
├── dashboard.css           # Styles
└── dashboard.js            # Client interactivity

HTTP 路由

路由	说明
/ or $kanban	仪表板视图
$kanban?dir=<path>	指定目录的仪表板
/api/plans	计划数据的 JSON API
/api/plans?dir=<path>	指定目录的 JSON API
/assets/*	静态资源
/file/*	本地文件服务

本地访问

除非你已明确接受公开本地文件服务带来的网络暴露风险，否则请在 localhost 上启动：

{
    "success": true,
    "url": "http://localhost:3500/kanban?dir=...",
    "port": 3500
}

计划结构

仪表板会扫描包含 plan.md 文件的目录：

plans/
├── 251215-feature-a/
│   ├── plan.md              # Required - parsed for phases
│   ├── phase-01-setup.md
│   └── phase-02-impl.md
├── 251214-feature-b/
│   └── plan.md
└── templates/               # Excluded by default

故障排除

端口已被占用：服务器会自动递增端口号，范围为 3500-3550

未找到计划：确保目录中包含 plan.md 文件

远程访问被拒绝：此仪表板仅供本地使用；除非你已明确接受网络暴露风险，否则请保留 --host localhost。

PID 文件：位于 /tmp/plans-kanban-*.pid

---

[重要] 开始前，使用任务跟踪将所有工作拆分成小任务——包括为每个要读取的文件创建任务。这可以防止因文件过长而丢失上下文。对于简单任务，AI 必须先询问用户是否跳过。

防止 AI 犯错——每项任务都要避免以下失败模式： 删除前检查下游引用。 删除组件会导致文档和代码逐步过时。移除前先梳理所有引用该组件的文件。 根据实际代码验证 AI 生成的内容。 AI 会臆造 API、类名和方法签名。记录或引用之前，务必使用 grep 确认它们确实存在。 编辑后追踪完整的依赖链。 更改定义时，可能会遗漏由此派生的下游变量和使用方。务必追踪完整链路。 验证正确性时追踪所有代码路径。 确认代码存在，不等于确认代码会执行。务必追踪提前退出、错误分支和条件跳过，不要只检查正常路径。 调试时，先问“这是谁的职责？”再修复。 追踪问题出在调用方（数据错误）还是被调用方（处理错误）。在负责的层级修复，绝不要只修补症状所在的位置。 假设现有值都是有意设置的——更改前先问为什么。 更改任何常量、限制、标志或模式之前：阅读注释、查看 git blame，并检查周边代码。 验证所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，需要验证每一个输出。一个检查通过，不代表所有检查都通过。 整体优先的调试方式——避免只关注眼前问题。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前提），然后逐项根据证据进行验证，再提出任何代码层面的假设。 精准修改——遵循差异测试。 修复 Bug 时：每一行更改都必须能直接追溯到该 Bug。不要顺手调整样式或改进相邻代码。增强任务：实现改进并明确说明。 编码前明确歧义——不要默默选择。 如果请求有多种解释，列出每种解释及其工作量估算并询问用户。绝不要擅自假设应处理所有记录、采用基于文件的方案或选择更复杂的路径。

批判性思维心态——运用批判性思维和顺序思维。每项主张都需要可追溯的证据，置信度超过 80% 才能采取行动。 反幻觉： 绝不要把猜测说成事实——每项主张都要引用来源，坦诚承认不确定性，自查输出中的错误，独立交叉核对，并对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。

必须注意运用批判性思维——每项主张都需要可追溯的证据，置信度超过 80% 才能采取行动。反幻觉：绝不要把猜测说成事实。

必须注意运用 AI 防错原则——整体优先调试、在负责的层级修复、编码前明确歧义，并在压缩上下文后重新阅读文件。

收尾提醒

重要，必须注意：开始前使用任务跟踪将工作拆分成小型待办任务 重要，必须注意：创建新代码前，在代码库中搜索 3 个或更多相似模式 重要，必须注意：每项主张都要引用 file:line 证据（置信度超过 80% 才能采取行动） 重要，必须注意：添加最终审查待办任务，以验证工作质量 重要，必须注意：在计划前置信息中加入“测试规范”部分和 story_points

[TASK-PLANNING] 行动前，分析任务范围，并使用任务跟踪系统地将其拆分成小型待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制执行，非常重要，必须遵守，至关重要。无论任何理由都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应保持项目中立；项目特定约定应从 docs/project-config.json 和 docs/project-reference/ 中发现。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要有此共享上下文和本地文档，任何受支持的 AI 工具均可执行。

1. 检测： 将提示词与工作流目录匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；但如果用户明确调用了某个工作流/技能，且本地协议将明确调用视为确认，则无需询问：
   • 问题：“你想启用哪个工作流？”
   • 选项 1：“启用 [BestMatch Workflow]（推荐）”
   • 选项 2：“启用自定义工作流：[step1 → step2 → ...]”（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；手动按顺序执行自定义步骤
5. 创建任务： 为工作流的所有步骤创建任务跟踪
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实陈述——每项主张都要引用来源，坦诚承认不确定性，自行检查输出是否有误，独立交叉验证，对自己的判断保持怀疑——毫无证据的确信是所有幻觉的根源。 AI 注意力原则（首因-近因）： 对于较长的提示词/协议，将最关键的 3 条规则同时放在开头和结尾，确保指令在长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，持续循环直到验证通过，只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则/不变量，并在受保护的意图遭到破坏时失败，而不是仅仅复现当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前，将工作拆分成小任务并进行任务跟踪。添加最终任务：“分析 AI 错误与经验教训”。

总结经验教训——仅关注根本原因，不要只修复表象：

1. 指明失败模式（推理/假设错误），而非表象——例如“未阅读源代码就假定 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境/代码库？如果不适用，则再抽象一层。
3. 写成通用规则——删去项目特定的名称/路径/类。此规则应适用于任何代码库。
4. 合并：多个错误若共享同一失败模式，则合并为一条经验教训。
5. 复发判断：“如果没有此提醒，这种情况会在未来的会话中再次发生吗？”——不会 → 跳过 $learn。
6. 自动修复判断：“$code-review/$code-simplifier/$security/$lint 能发现这个问题吗？”——能 → 改进审查技能。
7. 两项判断均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建/更新任务跟踪；之后在每个步骤开始/完成时保持同步。