flow-define

宿主：Codex CLI——此技能原为 Claude Code 设计，后适配至 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前启用的 Codex shell 和子 Agent 工具。当前会话尚未提供某个提供商、模型或宿主子 Agent 时，不要声称其可用。 宿主工具的对应项请参阅 skills/blocks/codex-host-adapter.md。

{{PREAMBLE}}

加载已安装插件中的 skills/blocks/engineering-method-selection.md， 并仅应用与此任务相关的方法。保留此入口的执行约定和输出格式。将引用的技能作为指令阅读； 不要递归调用当前命令，也不要从一个席位添加提供商调用。

共享定义

在适用时，加载项目现有的术语表和决策。如果不存在，请使用 skills/blocks/domain-modeling.md，并在当前设计文档中添加简短的定义部分。不要创建平行的上下文或记忆文件。 区分安装、身份验证、授权、就绪状态、计费、配额、席位、贡献和投票。

前置步骤：状态检查

开始定义前：

1. 阅读 .octo/STATE.md，确认发现阶段已完成
2. 更新 STATE.md：
   • current_phase: 2
   • phase_position: "Definition"
   • status: "in_progress"

# Verify Discover phase is complete
if [[ -f ".octo/STATE.md" ]]; then
  discover_status=$("${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" get_phase_status 1)
  if [[ "$discover_status" != "complete" ]]; then
    echo "⚠️ Warning: Discover phase not marked complete. Consider running discovery first."
  fi
fi

# Update state for Definition phase
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
  --phase 2 \
  --position "Definition" \
  --status "in_progress"

执行约定

此技能使用强制执行模式。必须严格遵循以下顺序。

步骤 1：显示可视化指示信息

强制要求：必须先使用原生命令行工具运行此提供商检查，然后才能显示横幅。不得跳过，也不得假定其可用。

provider_check_output=$(bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh")
provider_status_lines=$(printf '%s\n' "$provider_check_output" | awk '
  /^PROVIDER_CHECK_START$/ { capture=1; next }
  /^PROVIDER_CHECK_END$/ { capture=0 }
  capture && /^[a-z0-9-]+:(available|missing|degraded)$/ { print }
')

if [[ -z "$provider_status_lines" ]]; then
  echo "Provider availability check returned no usable status lines."
  exit 1
fi

# Exclude providers intentionally disabled by environment, session, or global
# allowlist policy; show every allowed provider, including missing/degraded.
source "${HOME}/.claude-octopus/plugin/scripts/lib/provider-allowlist.sh"
provider_availability=""
available_provider_count=0
while IFS=: read -r provider status; do
  octo_provider_allowed "$provider" || continue
  case "$status" in
    available)
      provider_availability="${provider_availability}🟢 ${provider}: Available ✓"$'\n'
      available_provider_count=$((available_provider_count + 1))
      ;;
    degraded)
      provider_availability="${provider_availability}🟠 ${provider}: Degraded ⚠"$'\n'
      ;;
    missing)
      provider_availability="${provider_availability}🔴 ${provider}: Missing/unavailable ✗"$'\n'
      ;;
  esac
done <<< "$provider_status_lines"

if [[ "$available_provider_count" -eq 0 ]]; then
  printf '%s' "$provider_availability"
  echo "No external provider is available. Run /octo:setup and retry."
  exit 1
fi

# Task status for the banner's Tasks line, if the session has one.
task_status=$("${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" get-task-status 2>/dev/null || echo "")

列出检查报告的所有提供商，而不只是 Claude。如果多个席位都已运行，横幅只显示一个席位会错误呈现用户的付费内容。

如果设置了 OCTO_ALLOWED_PROVIDERS，则将其视为允许参与的提供商的真实来源。被此允许列表筛除的提供商会被有意报告为不可用；不要在工作流中调用或推荐它们。

在执行 orchestrate.sh 之前显示此横幅：

🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider definition mode
🎯 Define Phase: [Brief description of what you're defining/scoping]
📋 Session: ${CLAUDE_SESSION_ID}
📝 Tasks: ${task_status}

Provider Availability:
${provider_availability}
🔵 Claude: Available ✓ - Consensus building and synthesis

💰 Estimated Cost: 0.01-0.05 USD
⏱️  Estimated Time: 2-5 minutes

横幅显示前不得继续执行步骤 2。 横幅会向用户显示将运行哪些提供商以及将产生哪些费用——在用户看不到这些信息时开始 API 调用，违反费用透明原则。

步骤 2：读取先前状态

执行工作流前，读取任何先前的上下文：

# Initialize state if needed
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" init_state

# Set current workflow
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" set_current_workflow "flow-define" "define"

# Get prior decisions (if any)
prior_decisions=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_decisions "all")

# Get context from discover phase
discover_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "discover")

# Display what you found (if any)
if [[ "$discover_context" != "null" ]]; then
  echo "📋 Building on discovery findings:"
  echo "  $discover_context"
fi

if [[ "$prior_decisions" != "[]" && "$prior_decisions" != "null" ]]; then
  echo "📋 Respecting prior decisions:"
  echo "$prior_decisions" | jq -r '.[] | "  - \(.decision) (\(.phase)): \(.rationale)"'
fi

其中包含以下上下文：

• 发现阶段的研究（如果已完成）
• 先前的架构决策
• 之前记录的用户愿景
• 如果已安装 claude-mem，则可使用其 MCP 工具（search、timeline、get_observations）查找类似主题的过往决策

读取状态前不得继续执行步骤 3。

步骤 3：阶段讨论——记录用户愿景

在执行成本较高的多 AI 协同编排前，记录用户愿景，以便有效界定工作范围。

使用 AskUserQuestion 提出澄清问题：

Use AskUserQuestion tool to ask:

1. **User Experience**
   Question: "How should users interact with this feature?"
   Header: "User Flow"
   Options:
   - label: "API-first (programmatic access)"
     description: "Build API endpoints first, UI later"
   - label: "UI-first (user-facing interface)"
     description: "Build user interface first, API supports it"
   - label: "Both simultaneously"
     description: "Develop API and UI in parallel"
   - label: "Not applicable"
     description: "This feature doesn't have a user interaction"

2. **Implementation Approach**
   Question: "What technical approach do you prefer?"
   Header: "Approach"
   Options:
   - label: "Fastest to market"
     description: "Prioritize speed, use existing libraries"
   - label: "Most maintainable"
     description: "Focus on clean architecture, may take longer"
   - label: "Best performance"
     description: "Optimize for speed and efficiency"
   - label: "Multi-LLM debate (Claude + available providers)"
     description: "Multiple AI models debate the best approach — may use external provider credits or subscriptions"

3. **Scope Boundaries**
   Question: "What's explicitly OUT of scope for this phase?"
   Header: "Out of Scope"
   Options:
   - label: "Testing and QA"
     description: "Focus on implementation, test later"
   - label: "Performance optimization"
     description: "Get it working first, optimize later"
   - label: "Edge cases"
     description: "Handle happy path only initially"
   - label: "Nothing excluded"
     description: "Everything is in scope"
   multiSelect: true

如果用户选择了“多大模型辩论（Claude + 可用提供商）”作为方案： 继续执行 orchestrate.sh 前，运行一次多大模型辩论以确定技术方案：

/octo:debate --rounds 2 --debate-style collaborative "What is the best technical approach for [feature]? Consider: speed to market, maintainability, performance, and the existing codebase patterns."

使用辩论综合结论，为定义阶段设定方案背景。

收集完答案后，创建上下文文件：

# Source context manager
source "${HOME}/.claude-octopus/plugin/scripts/context-manager.sh"

# Extract user answers from AskUserQuestion results
user_flow="[Answer from question 1]"
approach="[Answer from question 2]"
out_of_scope="[Answer from question 3]"

# Create context file with user vision
create_templated_context \
  "define" \
  "$(echo "$USER_REQUEST" | head -c 50)..." \
  "User wants: $user_flow approach with $approach priority" \
  "$approach" \
  "Implementation of requested feature" \
  "$out_of_scope"

echo "📋 Context captured and saved to .claude-octopus/context/define-context.md"

此上下文将用于：

• 界定多 AI 研究的范围（发现阶段）
• 聚焦需求定义（定义阶段）
• 指导实现决策（开发阶段）
• 根据用户预期进行验证（交付阶段）

捕获上下文前不得继续执行步骤 4。 用户愿景（UX 方案、优先级、范围外事项）决定了多 AI 研究的范围——缺少这些信息，提供商的研究范围会过宽，定义也会偏离用户的实际意图。

步骤 4：执行 orchestrate.sh define

你必须通过原生 shell 命令工具执行此命令：

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh define "<user's clarification request>"

重要：严禁：

• ❌ 不调用 orchestrate.sh，直接定义需求——单模型分析无法涵盖 provider 扇出机制提供的技术、业务和外部模型视角拆分，导致需求存在盲点
• ❌ 使用直接分析代替 orchestrate.sh
• ❌ 声称自己在“模拟”工作流
• ❌ 未运行此命令就继续执行步骤 5

你必须使用原生 shell 命令工具调用 orchestrate.sh。

执行期间用户看到的内容（v7.16.0+）

如果使用 Claude Code v2.1.16+ 运行，用户会在任务转轮中看到实时进度指示器：

阶段 1 - 外部提供方执行（并行）：

• 🔴 正在分析技术需求（Codex）...
• 🟡 正在明确用户需求和背景（Antigravity）...

阶段 2 - 综合（顺序执行）：

• 🔵 正在就问题定义达成共识...

这些转轮状态描述会自动更新——orchestrate.sh 会在每个 Agent 执行前调用 update_task_progress()。用户可以清楚地看到哪个提供方正在工作，以及它正在做什么。

**如果未使用 Claude Code v2.1.16+ 运行：**进度指示器会静默跳过，不显示错误。

步骤 5：验证执行情况

orchestrate.sh 完成后，验证其是否成功：

# Find the latest synthesis file (created within last 10 minutes)
SYNTHESIS_FILE=$(find ~/.claude-octopus/results -name "grasp-synthesis-*.md" -mmin -10 2>/dev/null | head -n1)

if [[ -z "$SYNTHESIS_FILE" ]]; then
  echo "❌ VALIDATION FAILED: No synthesis file found"
  echo "orchestrate.sh did not execute properly"
  exit 1
fi

echo "✅ VALIDATION PASSED: $SYNTHESIS_FILE"
cat "$SYNTHESIS_FILE"

如果验证失败：

1. 向用户报告错误
2. 显示 ~/.claude-octopus/logs/ 中的日志
3. 不要继续展示结果
4. 不要以直接分析替代——回退到单模型分析会违背多提供方共识的初衷，并导致需求范围更窄

步骤 6：更新状态

综合结果验证通过后，将发现和决策记录到状态中：

# Extract key definition from synthesis
key_definition=$(head -50 "$SYNTHESIS_FILE" | grep -A 3 "## Problem Definition\|## Summary" | tail -3 | tr '\n' ' ')

# Record any architectural decisions made
# (You should identify these from the synthesis - e.g., tech stack, approach, patterns)
decision_made=$(echo "$key_definition" | grep -o "decided to\|chose to\|selected\|using [A-Za-z0-9 ]*" | head -1)

if [[ -n "$decision_made" ]]; then
  "${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" write_decision \
    "define" \
    "$decision_made" \
    "Consensus from multi-AI definition phase"
fi

# Update define phase context
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_context \
  "define" \
  "$key_definition"

# Update metrics
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_metrics "phases_completed" "1"

状态更新完成前，不要继续执行步骤 7。

步骤 7：展示问题定义（仅在完成步骤 1-6 后）

读取综合结果文件并展示：

• 核心需求（必须具备、应该具备、最好具备）
• 技术约束
• 用户需求
• 需要处理的边缘情况
• 范围之外的事项
• 所有提供方的视角
• 需求检查清单
• 后续步骤（通常进入用于实现的 tangle 阶段）

注明来源：

*Multi-AI Problem Definition powered by Claude Octopus*
*Providers: available external providers + 🔵 Claude*
*Full problem definition: $SYNTHESIS_FILE*

Define 工作流 - Define 阶段 🎯

此工作流的作用

define 阶段使用外部 CLI 提供方明确问题并界定范围：

1. 🔴 Codex CLI - 分析技术需求、边缘情况和约束
2. 🟡 Antigravity CLI - 明确用户需求、业务需求并理解背景
3. 🧭 Antigravity CLI - 进一步引入外部模型进行审视
4. 🔵 Claude（你） - 综合问题并定义需求

这是 discovery 之后的收敛阶段——将宽泛的调研范围缩小到具体的问题定义。

何时使用 Define

在以下情况下使用 define：

• 定义需求：“准确定义身份验证系统需要实现什么”
• 明确问题：“明确缓存需求”
• 界定范围：“通知功能的范围是什么？”
• 识别约束：“X 的技术约束是什么？”
• 分析边缘情况：“Y 需要处理哪些边缘情况？”
• 验证需求：“Z 的这些需求是否完整？”

以下情况不要使用 define：

• 调研和探索（使用 probe-workflow）
• 构建实现（使用 tangle-workflow）
• 代码审查和验证（使用 ink-workflow）
• Claude 可以回答的简单问题

视觉指示器

执行前，你会看到以下形状的横幅。下方的提供方行仅供示例；应将其替换为步骤 1 中所有实时状态，并且只省略当前允许列表排除的提供方：

🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider problem definition
🎯 Define Phase: Clarifying requirements and scope
📋 Session: ${CLAUDE_SESSION_ID}
📝 Tasks: ${task_status}

Provider Availability:
🟢 codex: Available ✓
🧭 agy: Degraded ⚠
🔴 agy: Missing/unavailable ✗
🔵 Claude: Available ✓ - Consensus building and synthesis

工作原理

阶段 A：调用 Grasp 阶段

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh define "<user's clarification request>"

阶段 B：多提供方问题定义

orchestrate.sh 脚本将：

1. 调用 Codex CLI 进行技术需求分析
2. 调用 Antigravity CLI 分析业务／用户需求
3. 调用 Antigravity CLI 进行额外的外部模型挑战
4. 由你（Claude）综合结果，形成清晰的问题定义
5. 找出差距和缺失的需求

阶段 C：读取结果

结果保存至：

~/.claude-octopus/results/${SESSION_ID}/grasp-synthesis-<timestamp>.md

阶段 D：呈现问题定义

阅读综合结果，并向用户呈现清晰、可执行的需求。

实施说明

调用此技能时，请严格遵循上述 EXECUTION CONTRACT。该契约包括：

1. 阻塞步骤 1：检查提供方并显示实时状态指示器
2. 阻塞步骤 2：读取先前的工作流状态
3. 阻塞步骤 3：记录并持久化用户的愿景
4. 阻塞步骤 4：通过原生命令行工具执行 orchestrate.sh define
5. 阻塞步骤 5：验证综合结果文件是否存在
6. 阻塞步骤 6：更新工作流状态
7. 步骤 7：呈现格式化的问题定义

每个步骤都必须完成且具有阻塞性——只有当前步骤成功完成后，才能继续下一步。

任务管理集成

创建任务以跟踪执行进度：

// At start of skill execution
TaskCreate({
  subject: "Execute define workflow with multi-AI providers",
  description: "Run orchestrate.sh define for problem clarification",
  activeForm: "Running multi-AI define workflow"
})

// Mark in_progress when calling orchestrate.sh
TaskUpdate({taskId: "...", status: "in_progress"})

// Mark completed ONLY after synthesis file verified
TaskUpdate({taskId: "...", status: "completed"})

错误处理

如果任何步骤失败：

• 步骤 1（提供方）：如果所有外部提供方都不可用，建议使用 /octo:setup 并停止
• 步骤 4（orchestrate.sh）：显示 bash 错误，检查日志，并向用户报告
• 步骤 5（验证）：如果综合结果缺失，显示 orchestrate.sh 日志，且不要改用直接分析

如果 orchestrate.sh 执行失败，绝不要改用直接分析。报告失败情况，并由用户决定如何继续。

问题定义格式

成功执行后，按以下格式呈现问题定义：

# Problem Definition: <task>

## Core Requirements
[Essential requirements that must be met]

## Technical Constraints
[Technical limitations and considerations]

## User Needs
[What users actually need from this]

## Edge Cases to Handle
[Specific edge cases identified]

## Out of Scope
[What is explicitly NOT included]

## Perspectives

### Codex Analysis (Technical)
[Technical requirements and constraints]

### Antigravity Analysis (Business/User)
[User needs and business context]

### Claude Synthesis
[Integrated problem definition]

## Requirements Checklist
- [ ] Functional requirements defined
- [ ] Non-functional requirements defined
- [ ] Technical constraints identified
- [ ] Edge cases documented
- [ ] Out-of-scope items clarified
- [ ] Success criteria established

## Next Steps
[Recommended next actions - usually tangle phase for implementation]

Full problem definition saved to: <synthesis file path>

使用示例

示例 1：定义身份验证需求

User: Define the exact requirements for our user authentication system

Claude:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider problem definition
🎯 Define Phase: Clarifying authentication requirements

[Executes: ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh define "Define exact requirements for user authentication system"]

[After completion, reads synthesis and presents:]

# Problem Definition: User Authentication System

## Core Requirements

### Must Have (P0)
1. User registration with email + password
2. Secure login with JWT token generation
3. Password reset via email
4. Session management with token refresh
5. Logout (token invalidation)

### Should Have (P1)
6. Remember me functionality
7. Account lockout after failed attempts
8. Email verification on signup
9. Password strength requirements

### Nice to Have (P2)
10. OAuth social login (Google, GitHub)
11. Two-factor authentication
12. Single sign-on (SSO)

## Technical Constraints

- Must work with existing Express.js backend
- Token storage: Redis for production, in-memory for dev
- Password hashing: bcrypt (min 12 rounds)
- Token expiry: Access token 15min, refresh token 7 days
- Rate limiting: Max 5 login attempts per 15min per IP

## User Needs

- Simple registration process (< 2 minutes)
- Secure password recovery without support tickets
- Stay logged in across browser sessions (remember me)
- Clear error messages for failed login
- Ability to log out from all devices

## Edge Cases to Handle

1. **Concurrent logins**: Same user, multiple devices
2. **Expired tokens**: Graceful refresh without re-login
3. **Password reset race condition**: Multiple reset requests
4. **Account enumeration**: Don't reveal if email exists
5. **Token theft**: Detect suspicious login locations
6. **Deleted users**: Handle auth for soft-deleted accounts

## Out of Scope

- ❌ Biometric authentication (fingerprint, face ID)
- ❌ LDAP/Active Directory integration
- ❌ Custom OAuth provider implementation
- ❌ Device fingerprinting
- ❌ Passwordless email magic links

## Perspectives

### Codex Analysis (Technical)
- JWT structure: { userId, role, exp, iat, jti }
- Database schema for users, refresh_tokens, password_resets
- API endpoints: POST /register, POST /login, POST /logout, POST /refresh, POST /reset-password
- Middleware for auth verification
- Security: HTTPS only, secure cookies, CSRF protection

### Antigravity Analysis (Business/User)
- User journey: Registration -> Email verification -> Login -> Access app
- Error handling: Clear messages without security leaks
- Performance: Auth checks < 50ms
- Compliance: GDPR (data deletion), password policies
- Analytics: Track signup conversion, failed login rates

### Claude Synthesis
- Hybrid approach: Core auth (P0) first, iterate on P1/P2
- Security-first: All requirements validated against OWASP
- User experience: Balance security with convenience
- Scalable: Design for 100K users, plan for 1M+

## Requirements Checklist
- ✅ Functional requirements defined (registration, login, reset)
- ✅ Non-functional requirements defined (performance, security)
- ✅ Technical constraints identified (Express, Redis, bcrypt)
- ✅ Edge cases documented (6 critical cases)
- ✅ Out-of-scope items clarified (4 items)
- ✅ Success criteria established (< 2min registration, < 50ms auth)

## Next Steps

1. **Immediate**: Review and confirm requirements with stakeholders
2. **Then**: Use **tangle-workflow** to implement the auth system
3. **Finally**: Use **ink-workflow** to validate implementation

Ready to proceed to implementation?

Full problem definition saved to: ~/.claude-octopus/results/abc-123/grasp-synthesis-20250118-144530.md

示例 2：明确功能范围

User: What exactly does the notification feature need to do?

Claude:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider problem definition
🎯 Define Phase: Clarifying notification requirements

[Executes grasp workflow]

[Presents detailed problem definition with:]
- Core notification types (email, push, in-app)
- Delivery requirements (real-time vs batched)
- User preferences (opt-in/out, frequency)
- Technical constraints (message queue, delivery tracking)
- Edge cases (offline users, rate limits)

Ready to build once requirements are confirmed.

与其他工作流的集成

Grasp 是 Double Diamond 的第二阶段：

PROBE (Discover) → GRASP (Define) → TANGLE (Develop) → INK (Deliver)

典型流程：

1. Probe：“研究身份验证最佳实践”（探索选项）
2. Grasp：“明确我们的身份验证系统的具体需求”（缩小范围）
3. Tangle：“实现身份验证系统”（构建）
4. Ink：“验证身份验证实现”（交付）

如果需求不明确，也可以单独使用 grasp。

质量检查清单

完成 grasp 工作流之前，请确保：

• 核心需求已明确定义（必须有、应该有、最好有）
• 技术约束已记录
• 已了解并清晰阐述用户需求
• 边缘情况已识别并记录
• 已明确列出范围之外的事项
• 已制定成功标准
• 已向用户建议后续步骤
• 已分享完整的问题定义

成本提示

外部 API 使用：

• 🔴 Codex CLI 使用你的 OPENAI_API_KEY（会产生费用）
• 🟡 Antigravity CLI 使用你的 AGY_AUTH_TOKEN（会产生费用）
• 🧭 Antigravity CLI 使用你的 Antigravity 账户／模型配置（可能会产生费用）
• 🔵 Claude 分析已包含在 Claude Code 中

Grasp 工作流通常每项任务花费 0.01–0.05 美元，具体取决于复杂程度。

定义后：更新状态

定义完成后：

1. 更新 .octo/STATE.md，记录完成情况
2. 在 .octo/ROADMAP.md 中填写已定义的阶段和成功标准

# Update state after Definition completion
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
  --status "complete" \
  --history "Define phase completed"

# Populate ROADMAP.md with defined requirements
if [[ -f "$SYNTHESIS_FILE" ]]; then
  echo "📝 Updating .octo/ROADMAP.md with defined phases..."
  "${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_roadmap \
    --from-synthesis "$SYNTHESIS_FILE"
fi

终止状态

只有在需求完成综合且用户批准范围后，Define 阶段才算完成。获得批准后，如果用户要求实施，则调用 flow-develop。 否则，交付需求文档并停止。未获批准的范围不得在此处开始 实施。

准备好进行定义！ 此技能仅在用户明确调用后使用，适用于用户要求澄清需求或定义问题的情形。