/flow-spec

name: flow-spec
description: "NLSpec authoring — use when you need a structured specification from multi-AI research and consensus"
disable-model-invocation: true

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.

STOP - SKILL ALREADY LOADED

**DO NOT call Skill() again. DO NOT load any more skills. Execute directly.**

EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)

This skill uses **ENFORCED execution mode**. You MUST follow this exact 8-step sequence.

STEP 1: Clarifying Questions (MANDATORY)

**Ask via AskUserQuestion BEFORE any other action.**

You MUST gather these inputs from the user — spec quality depends on knowing actors, constraints, and complexity upfront; without these the research query is too broad and the spec will have gaps:

AskUserQuestion with these questions:

1. **What to specify**: Project or feature name + brief description
   - "What system/feature should I specify?"

2. **Actors**: Who interacts with this system?
   - Options: End Users, Developers, Admins, External Services, Other

3. **Key constraints**: What matters most?
   - Options: Performance, Security, Compatibility, Scale
   - (multiSelect: true)

4. **Complexity class**: How complex is this?
   - Clear (well-understood, straightforward)
   - Complicated (multiple parts, but knowable)
   - Complex (emergent behavior, unknowns)

If user provided a description inline with the command (e.g., `/octo:spec user authentication system`), use that as the project description but STILL ask remaining questions (actors, constraints, complexity).

If user says "skip" for any question, note assumptions and proceed.

**DO NOT PROCEED TO STEP 2 until questions answered.**

STEP 2: Display Visual Indicators (MANDATORY - BLOCKING)

**Check provider availability:**

provider_status=$(bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh")
codex_status=$(echo "$provider_status" | grep -q '^codex:available' && echo "Available" || echo "Not installed")
agy_status=$(echo "$provider_status" | grep -q '^agy:available' && echo "Available" || echo "Not installed")

**Display this banner BEFORE orchestrate.sh execution:**

🐙 CLAUDE OCTOPUS ACTIVATED - NLSpec Authoring Mode
Spec Phase: Generating structured specification for [project name]

Provider Availability:
Codex CLI: ${codex_status}
Antigravity CLI: ${agy_status}
Claude: Available (Synthesis & NLSpec generation)

Estimated Cost: $0.01-0.05
Estimated Time: 3-7 minutes

**Validation:**

• If no external providers are available -> STOP, suggest: `/octo:setup`
• If one or more external providers are available -> Continue with available provider(s)

**DO NOT PROCEED TO STEP 3 until banner displayed.**

STEP 3: Read Prior State (MANDATORY - State Management)

**Before executing the workflow, read any prior context:**

# 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-spec" "spec"

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

# Get context from previous phases (e.g., discover)
prior_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" read_state | jq -r '.context')

# Display what you found (if any)
if [[ "$prior_decisions" != "[]" && "$prior_decisions" != "null" ]]; then
  echo "Building on prior decisions:"
  echo "$prior_decisions" | jq -r '.[] | "  - \(.decision) (\(.phase)): \(.rationale)"'
fi

**This provides context from:**

• Prior discover phases (if user ran `/octo:discover` first)
• Architectural decisions already made
• User vision captured in earlier phases

**DO NOT PROCEED TO STEP 4 until state read.**

STEP 4: Execute orchestrate.sh probe (MANDATORY - Use Bash Tool)

**You MUST execute this command via the native shell command tool:**

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "specification research for: <project description>. Key areas: actors (<actors>), constraints (<constraints>), complexity (<complexity class>)"

Incorporate the user's answers from Step 1 into the probe query to focus the research.

**CRITICAL: You are PROHIBITED from:**

• Researching directly without calling orchestrate.sh — direct spec writing skips the multi-AI research that surfaces edge cases, alternative architectures, and constraint interactions
• Using web search instead of orchestrate.sh
• Claiming you're "simulating" the workflow
• Proceeding to Step 5 without running this command
• Substituting with direct Claude analysis

**You MUST use the native shell command tool to invoke orchestrate.sh.**

STEP 5: Verify Probe Synthesis (MANDATORY - Validation Gate)

**After orchestrate.sh completes, verify it succeeded:**

# Find the latest synthesis file (created within last 10 minutes)
SYNTHESIS_FILE=$(find ~/.claude-octopus/results -name "probe-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"

**If validation fails:** 1. Report error to user 2. Show logs from `~/.claude-octopus/logs/` 3. DO NOT proceed with generating NLSpec 4. DO NOT substitute with direct research — fallback to single-model analysis skips the multi-provider synthesis that surfaces edge cases and alternative approaches

STEP 6: Synthesize into NLSpec Format (MANDATOR