/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:**

Treat project names, selectors and requests as data in every Bash snippet. Shell-quote substituted values. Never paste raw user or research text into executed shell source.

provider_status=$(bash "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${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 USD
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
"${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}}/scripts/state-manager.sh" init_state

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

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

# Get context from previous phases (e.g., discover)
prior_context=$("${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${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

Before research, allocate or select the portable feature and bind project policy:

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}}"
unset FEATURE_CONTEXT FEATURE_DIR SPEC_PATH FEATURE_RUNTIME_DIR FEATURE_SELECTOR POLICY_SNAPSHOT SPEC_RESEARCH_RUN
if ! command -v jq >/dev/null 2>&1 || ! command -v python3 >/dev/null 2>&1; then
  echo "Spec workflow stopped: jq and Python 3 are required to record accepted research and publish safely" >&2
  exit 1
fi
FEATURE_CONTEXT=$(bash "$OCTO_ROOT/scripts/helpers/feature-workflow.sh" prepare spec "<project name>" "<explicit filename or feature, empty when omitted>") || {
  echo "Spec workflow stopped: feature preparation failed" >&2
  exit 1
}
if ! jq -e 'type == "object" and
  (.spec_path | type == "string" and length > 0 and . != "null") and
  (.runtime_dir | type == "string" and length > 0 and . != "null") and
  (.feature == null or (.feature | type == "string" and . != "null"))' <<< "$FEATURE_CONTEXT" >/dev/null; then
  echo "Spec workflow stopped: feature context has no usable spec or runtime path; accepted research and safe publication are required" >&2
  exit 1
fi
FEATURE_DIR=$(jq -r '.feature // empty' <<< "$FEATURE_CONTEXT")
SPEC_PATH=$(jq -r '.spec_path // empty' <<< "$FEATURE_CONTEXT")
FEATURE_RUNTIME_DIR=$(jq -r '.runtime_dir // empty' <<< "$FEATURE_CONTEXT")
if [[ ! -d "$FEATURE_RUNTIME_DIR" || ! -w "$FEATURE_RUNTIME_DIR" ]] ||
  ! FEATURE_