app-brief

app-brief 根据 APP_DEFINITION.md 生成或更新应用简报。首次运行时，从头创建 APP_BRIEF.md。后续运行时，检测 APP_DEFINITION.md 中的变更，并增量更新现有简报。 /app-brief

运行前检查

继续之前，请确认当前目录是已搭建的 Cribl 应用文件夹。如果不是，请停止并告知用户：“你必须在已搭建的 Cribl 应用文件夹中运行此技能。”

**触发条件：**在 APP_DEFINITION.md 所在的同一文件夹中运行此技能。

**输入：**APP_DEFINITION.md 的内容（更新时可选提供现有的 APP_BRIEF.md）

**输出：**一份完整的应用简报（支持全面编辑），供 Claude Code 用于实现应用，并保存到 APP_BRIEF.md

使用方法

1. cd 到应用目录
2. 运行此技能：/app-brief
   • 首次运行：根据定义创建 APP_BRIEF.md
   • 后续运行：根据 APP_DEFINITION.md 中的变更更新 APP_BRIEF.md
3. 检查并编辑生成的简报
4. 运行 /app-validate 技能
5. 如果验证失败，请修正简报。
6. 将 app-brief 的内容传递给你的 Agent 工具（Claude Code）

技能工作流

第 1 步：检查是否已有简报

• 如果 APP_BRIEF.md 不存在：运行“生成简报”工作流（见下文）
• 如果 APP_BRIEF.md 已存在：运行“更新简报”工作流（见下文）

第 2A 步：生成简报（首次运行）

如果 APP_BRIEF.md 不存在，请根据 APP_DEFINITION.md 中提供的答案，从头生成实现简报。

# [App Name] - App Brief

## App ID
[The unique identifier for this app]

## Problem & Vision
[Summary of the problem the app solves and how users benefit]

## Target Users
[Who uses this app and what they're trying to accomplish]

## Key Workflows
### Workflow 1: [Name]
- **User sees**: [What appears on screen]
- **User does**: [What they click/configure/select]
- **Result**: [What gets created/changed/shown]
- **Permissions**: [Who can do this? Any restrictions?]

### Workflow 2: [Name]
- **User sees**: [What appears on screen]
- **User does**: [What they click/configure/select]
- **Result**: [What gets created/changed/shown]
- **Permissions**: [Who can do this? Any restrictions?]

[+ Additional workflows as needed]

## Data & Actions
**The app will fetch from Cribl:**
- [Resource type 1]: [Why? Used in which workflow?]
- [Resource type 2]: [Why? Used in which workflow?]

**The app will create/modify/delete in Cribl:**
- [Resource type 1]: [Which workflow creates/modifies/deletes this?]
- [Resource type 2]: [Which workflow creates/modifies/deletes this?]

**The app will remember (general state):**
- [State 1]: [What should be saved? When should it persist?]
- [State 2]: [What should be saved? When should it persist?]

(Or "None" if no general state)

**User-specific settings (stored per user):**
- [Setting 1]: [What is it? Which user(s) need it?]
- [Setting 2]: [What is it? Which user(s) need it?]

(Or "None" if no per-user settings)

**Secure secrets:**
- [Secret 1]: [What is it? How is it used?]
- [Secret 2]: [What is it? How is it used?]

(Or "None" if no secrets)

## UI Structure
### Overall Layout
[Recommended structure: wizard, dashboard, form, table, etc.]

### Key Screens/Pages
1. **[Screen Name]**: [What it shows, what user can interact with]
2. **[Screen Name]**: [What it shows, what user can interact with]
3. **[Screen Name]**: [What it shows, what user can interact with]

[Add more screens as needed]

## Permissions & Access
- **Who can use this app?**: [All members, or specific roles?]
- **Permission-aware behavior**: [How does the app respond if a user lacks access to an action?]

## External Integrations (if any)
- **[Service name]**: [What does the app do with it?]
- **[Service name]**: [What does the app do with it?]

(Or "None" if the app only works with Cribl)

## MVP Scope
**Must-have:**
- [Feature 1]
- [Feature 2]

**Nice-to-have (defer):**
- [Feature 1]
- [Feature 2]

**Out of scope:**
- [Feature 1]

## Edge Cases & Error Handling
- **If user lacks permission**: [What should the app show?]
- **If data is unavailable**: [What should the app show?]
- **If an action fails**: [What should the app show?]

## Implementation guidance (include this section verbatim)
- Read AGENTS.md first
- Then read openapi.json
- NEVER EVER use local storage 

---

第 2B 步：更新简报（后续运行）

如果 APP_BRIEF.md 已存在，请根据 APP_DEFINITION.md 中的变更智能地更新：

检测与合并逻辑：

1. 比较两个文件，确定 APP_DEFINITION.md 中有哪些变更：

   • 应用 ID 变更
   • 新增工作流
   • 工作流修改（名称、描述或步骤变更）
   • 新增数据需求（新的获取来源、创建/修改/删除操作、状态字段）
   • 新增 UI 屏幕或布局变更
   • 新增范围条目（必需项、可选项、范围外项目）
   • 权限、集成或边缘情况变更

2. 对于新增工作流：按照现有工作流的格式，将其添加到 APP_BRIEF.md 的“## Key Workflows”部分

3. 对于修改的工作流：使用新详情更新对应的工作流部分，同时保留简报中已有、但定义中未包含的补充说明或示例

4. 对于新增数据需求：将其添加到“## Data & Actions”部分下对应的小节（获取、创建/修改/删除、状态、设置、机密）

5. 对于新增 UI 屏幕：将其添加到“## UI Structure”部分的“Key Screens/Pages”列表中

6. 对于范围变更：将新增项目添加到“## MVP Scope”下对应的小节

7. 对于其他变更：更新相关部分（问题与愿景、目标用户、权限与访问、外部集成、边缘情况与错误处理）

保留规则：

• 不得删除 APP_BRIEF.md 中存在、但更新后的 APP_DEFINITION.md 未提及的任何部分或工作流
• 保留简报中超出定义内容的补充说明、示例或实现细节
• 如果定义中的工作流描述更详细，则替换简报中的版本；如果简报中的描述更详细，则予以保留
• 始终原样保留“## Implementation guidance”部分

输出：

• 显示变更摘要：“新增 1 个工作流：[名称]。更新 2 个工作流：[名称]。新增 3 项数据需求。”
• 将更新后的简报保存回 APP_BRIEF.md
• 显示已更新的部分，供用户检查

工作流结束

生成或更新简报后，最终简报即可用于：

• 首次运行：检查并按需编辑，然后运行 /app-validate 验证一致性
• 后续运行：检查差异摘要，查看更新的部分，然后通过 /app-implement 提交更改

---

核心原则

• 不使用技术术语：用户描述问题；由 Claude 确定实现方式
• Markdown 持久化：易于阅读、编辑和进行版本控制
• 迭代更新：可随着需求变化重新生成或更新简报
• 增量更新：仅重写发生变化的部分；保留现有的详细内容
• 直接编辑文件：用户可直接编辑 APP_BRIEF.md，以便快速迭代
• 由 Claude 处理 API：Claude 使用 openapi.json 确定要调用哪些 Cribl API
• 按用户存储：每位用户的设置都会自动添加用户 ID 前缀
• 优先构建 MVP：鼓励先发布最精简的版本，再迭代完善
• 仅列出外部集成：仅在应用会调用第三方服务时列出
• 单一事实来源：APP_DEFINITION.md 是权威来源；其中的更改会推动简报更新

示例工作流：添加新功能

1. 编辑 APP_DEFINITION.md，添加一个新工作流（例如“批量启用/禁用集成”）
2. 运行 /app-brief — 该技能会检测到新工作流，并将其添加到简报中
3. 查看更新后的简报，确认新工作流已融入现有工作流
4. 运行 /app-validate，确保更新后的简报合理
5. 运行 /app-implement，实现新工作流

资源

• Cribl 应用文档：https://docs.cribl.io/apps/
• 构建指南：https://docs.cribl.io/apps/builder-guide/
• GitHub 示例：https://github.com/criblapps 和 https://github.com/Cribl-Community