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")
gemini_status=$(echo "$provider_status" | grep -q '^gemini: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}
Gemini CLI: ${gemini_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:discoverfirst) - 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 Bash 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 Bash 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:
- Report error to user
- Show logs from
~/.claude-octopus/logs/ - DO NOT proceed with generating NLSpec
- 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 (MANDATORY)
Read the probe synthesis file from Step 5 and the user's answers from Step 1.
Synthesize into the NLSpec template below. This is YOUR (Claude's) synthesis role - you read the multi-AI research and structure it into the specification format.
NLSpec Template:
# NLSpec: [Project Name]
## Meta
- Version: 1.0.0
- Author: [human author from user context, or "TBD"]
- Created: [today's date]
- Complexity: [clear | complicated | complex - from Step 1]
## Purpose
[1-3 sentences: what this software does and for whom. Derived from user description + probe research.]
## Actors
- **[Actor 1]**: [Role description and capabilities]
- **[Actor 2]**: [Role description and capabilities]
[Include all actors from Step 1 answers + any discovered in research]
## Behaviors
### B1: [Behavior Name]
- **Trigger**: [What initiates this behavior]
- **Preconditions**: [What must be true before execution]
- **Steps**:
1. [Step 1]
2. [Step 2]
- **Postconditions**: [What must be true after execution]
- **Edge Cases**:
- [Edge case]: [Expected handling]
### B2: [Behavior Name]
- **Trigger**: [What initiates this behavior]
- **Preconditions**: [What must be true before execution]
- **Steps**:
1. [Step 1]
- **Postconditions**: [What must be true after execution]
- **Edge Cases**:
- [Edge case]: [Expected handling]
[Add as many behaviors as the research and scope warrant. Aim for 3-7 core behaviors.]
## Constraints
- **Performance**: [Latency, throughput requirements]
- **Security**: [Authentication, authorization, data handling]
- **Compatibility**: [APIs, platforms, browsers, versions]
- **Scale**: [Expected load, data volume, growth projections]
[Populate from Step 1 constraint answers + probe research findings]
## Dependencies
- **External Services**: [APIs, databases, third-party services]
- **Libraries/Frameworks**: [Required packages, minimum versions]
## Acceptance Definition
- **Satisfaction Target**: [0.0-1.0, e.g., 0.90 - based on complexity class]
- **Critical Behaviors**: [Which behaviors must achieve 1.0 satisfaction]
Guidelines for synthesis:
- Use research findings to fill in realistic, specific values (not placeholders)
- Behaviors should be concrete and testable, not vague
- Constraints should have measurable targets where possible
- For "clear" complexity: aim for 0.95 satisfaction target
- For "complicated" complexity: aim for 0.90 satisfaction target
- For "co