moflo 4.8.21 → 4.8.23

package/.claude/skills/fl/SKILL.md

@@ -1,583 +1,583 @@
----
-name: flo
-description: MoFlo ticket workflow - analyze and execute GitHub issues
-arguments: "[options] <issue-number | title>"
----
-
-# /flo - MoFlo Ticket Workflow
-
-Research, create tickets for, and execute GitHub issues automatically.
-
-**Arguments:** $ARGUMENTS
-
-## Usage
-
-```
-/flo <issue-number>                   # Full workflow in NORMAL mode (default)
-/flo -t <issue-number>                # Ticket only: research and update ticket, then STOP
-/flo -t <title>                       # Create a NEW ticket with description, acceptance criteria, test cases
-/flo --ticket <issue-number|title>    # Same as -t
-/flo -r <issue-number>                # Research only: analyze issue, output findings
-/flo --research <issue-number>        # Same as -r
-```
-
-Also available as `/fl` (shorthand alias).
-
-### Execution Mode (how work is done)
-
-```
-/flo 123                              # NORMAL mode (default) - single-agent execution
-/flo -s 123                           # SWARM mode - multi-agent coordination
-/flo --swarm 123                      # Same as -s
-/flo -h 123                           # HIVE-MIND mode - consensus-based coordination
-/flo --hive 123                       # Same as -h
-/flo -n 123                           # NORMAL mode - single Claude, no agents
-/flo --normal 123                     # Same as -n
-```
-
-### Epic Handling
-
-```
-/flo 42                               # If #42 is an epic, processes all stories sequentially
-```
-
-**Epic Detection:** An issue is automatically detected as an epic if ANY of these are true:
-- Has a label matching: `epic`, `tracking`, `parent`, or `umbrella` (case-insensitive)
-- Body contains `## Stories` or `## Tasks` sections
-- Body has checklist-linked issues: `- [ ] #123`
-- Body has numbered issue references: `1. #123`
-- The issue has GitHub sub-issues (via `subIssues` API field)
-
-**Sequential Processing:** When an epic is selected:
-1. List all child stories/tasks (from checklist or linked issues)
-2. Process each story **one at a time** in order
-3. Each story goes through the full workflow (research -> ticket -> implement -> test -> PR)
-4. After each story's PR is created, move to the next story
-5. Continue until all stories are complete
-
-### Combined Examples
-
-```
-/flo 123                              # Normal + full workflow (default) - includes ALL tests
-/flo 42                               # If #42 is epic, processes stories sequentially
-/flo -s 123                           # Swarm + full workflow (multi-agent coordination)
-/flo -t 123                           # Normal + ticket only (no implementation)
-/flo -h -t 123                        # Hive-mind + ticket only
-/flo -s -r 123                        # Swarm + research only
-/flo --swarm --ticket 123             # Explicit swarm + ticket only
-/flo -n 123                           # Normal (explicit, same as default)
-```
-
-## NORMAL MODE IS THE DEFAULT
-
-By default, /flo runs in NORMAL mode — single-agent execution without
-spawning sub-agents. This is efficient for most tasks.
-
-Use `-s`/`--swarm` for multi-agent coordination when the task warrants it.
-Use `-h`/`--hive` for consensus-based coordination on architecture decisions.
-
-POST-TASK NEURAL LEARNING ALWAYS RUNS regardless of execution mode.
-The hooks system collects learnings after every task completion — normal,
-swarm, or hive-mind.
-
-## COMPREHENSIVE TESTING REQUIREMENT
-
-ALL tests MUST pass BEFORE PR creation - NO EXCEPTIONS.
-- Unit Tests: MANDATORY for all new/modified code
-- Integration Tests: MANDATORY for API endpoints and services
-- E2E Tests: MANDATORY for user-facing features
-PR CANNOT BE CREATED until all relevant tests pass.
-
-## Workflow Overview
-
-```
-Research -> Ticket -> Execute -> Testing -> Simplify -> PR+Done
-
-Research:    Fetch issue, search memory, read guidance, find files
-Ticket:      Create or update GitHub issue with description, acceptance criteria, test cases
-Execute:     Assign self, create branch, implement changes
-Testing:     Unit + Integration + E2E tests (ALL MUST PASS - gate)
-Simplify:    Run /simplify on changed code (gate - must run before PR)
-PR+Done:     Create PR, update issue status, store learnings
-```
-
-### Workflow Gates
-
-| Gate | Requirement | Blocked Action |
-|------|-------------|----------------|
-| **Testing Gate** | Unit + Integration + E2E must pass | PR creation |
-| **Simplification Gate** | /simplify must run on changed files | PR creation |
-
-### Execution Mode (applies to all phases)
-
-| Mode | Description |
-|------|-------------|
-| **NORMAL** (default) | Single Claude execution. Efficient for most tasks. |
-| **SWARM** (-s) | Multi-agent via Task tool: researcher, coder, tester, reviewer |
-| **HIVE-MIND** (-h) | Consensus-based coordination for architecture decisions |
-
-## Phase 1: Research (-r or default first step)
-
-### 1.1 Fetch Issue Details
-```bash
-gh issue view <issue-number> --json number,title,body,labels,state,assignees,comments,milestone
-```
-
-### 1.2 Check Ticket Status
-Look for `## Acceptance Criteria` marker in issue body.
-- **If present**: Ticket already enhanced, skip to execute or confirm
-- **If absent**: Proceed with research and ticket update
-
-### 1.3 Search Memory FIRST
-ALWAYS search memory BEFORE reading guidance or docs files.
-Memory has file paths, context, and patterns - often all you need.
-Only read guidance files if memory search returns zero relevant results.
-
-```bash
-npx flo memory search --query "<issue title keywords>" --namespace patterns
-npx flo memory search --query "<domain keywords>" --namespace guidance
-```
-
-Or via MCP: `mcp__moflo__memory_search`
-
-### 1.4 Read Guidance Docs (ONLY if memory insufficient)
-**Only if memory search returned < 3 relevant results**, read guidance files:
-- Bug -> testing patterns, error handling
-- Feature -> domain model, architecture
-- UI -> frontend patterns, components
-
-### 1.5 Research Codebase
-Use Task tool with Explore agent to find:
-- Affected files and their current state
-- Related code and dependencies
-- Existing patterns to follow
-- Test coverage gaps
-
-## Phase 2: Ticket (-t creates or updates a ticket)
-
-When given an issue number, `-t` enhances the existing ticket. When given a title (non-numeric argument), `-t` creates a new GitHub issue. Either way, the ticket MUST include all three of the following sections.
-
-### 2.0 Complexity Assessment (MANDATORY before building ticket)
-
-After research, assess the complexity of the work. This determines whether the issue stays as a single ticket or gets promoted to an epic with sub-issues.
-
-**Complexity Signals — count how many apply:**
-
-| Signal | Weight | Example |
-|--------|--------|---------|
-| Multiple files changed (5+) | +2 | Touches models, API, tests, docs, config |
-| New module or package | +2 | Requires new directory structure |
-| Cross-cutting concern | +2 | Auth, logging, error handling across layers |
-| Database/schema changes | +2 | Migrations, new tables, index changes |
-| Multiple independent work streams | +3 | Frontend + backend + infra changes |
-| External API integration | +1 | Third-party service, webhook, OAuth |
-| Breaking change / migration | +2 | Requires deprecation, data migration |
-| Significant test surface | +1 | Needs 10+ new test cases across categories |
-| Security implications | +1 | Authentication, authorization, input validation |
-| UI + backend changes together | +2 | Full-stack feature spanning layers |
-
-**Complexity Thresholds:**
-
-| Score | Classification | Action |
-|-------|---------------|--------|
-| 0–3 | **Simple** | Single ticket — proceed normally |
-| 4–6 | **Moderate** | Single ticket — flag in description that it may benefit from splitting |
-| 7+ | **Complex** | **PROMOTE TO EPIC** — decompose into sub-issues |
-
-**When promoting to epic:**
-
-1. Decompose the work into 2–6 independent, shippable stories
-2. Each story should be completable in a single PR
-3. Stories should have clear boundaries (one concern per story)
-4. Order stories by dependency (independent ones first)
-5. Create each story as a GitHub issue with its own Description, Acceptance Criteria, and Test Cases
-6. Create or convert the parent issue into an epic with a `## Stories` checklist
-
-```javascript
-// Complexity assessment pseudocode
-function assessComplexity(research) {
-  let score = 0;
-  if (research.affectedFiles.length >= 5) score += 2;
-  if (research.requiresNewModule) score += 2;
-  if (research.crossCutting) score += 2;
-  if (research.schemaChanges) score += 2;
-  if (research.independentWorkStreams >= 2) score += 3;
-  if (research.externalAPIs) score += 1;
-  if (research.breakingChanges) score += 2;
-  if (research.estimatedTestCases >= 10) score += 1;
-  if (research.securityImplications) score += 1;
-  if (research.fullStack) score += 2;
-  return score;
-}
-```
-
-### 2.0.1 Epic Decomposition (when score >= 7)
-
-When complexity warrants an epic, decompose into stories:
-
-```bash
-# Step 1: Create each sub-issue
-gh issue create --title "Story: <story-title>" --body "<## Description + ## Acceptance Criteria + ## Suggested Test Cases>" --label "story"
-# Capture the new issue number from output
-
-# Step 2: Repeat for all stories (2-6 stories typically)
-
-# Step 3: Build the epic body with checklist referencing ALL story issue numbers
-# Step 4: If updating an existing issue, convert it to epic:
-gh issue edit <parent-number> --add-label "epic" --body "<epic body with ## Stories checklist>"
-
-# Step 5: If creating new, create the epic:
-gh issue create --title "Epic: <title>" --label "epic" --body "<epic body>"
-```
-
-**Epic body format (MANDATORY — this is how tracking works):**
-
-```markdown
-## Overview
-<High-level description of the epic goal>
-
-## Stories
-
-- [ ] #<story-1-number> <story-1-title>
-- [ ] #<story-2-number> <story-2-title>
-- [ ] #<story-3-number> <story-3-title>
-
-## Complexity Assessment
-Score: <N>/20 — <Simple|Moderate|Complex>
-Signals: <list of signals that triggered>
-```
-
-The `## Stories` checklist with `- [ ] #<number>` format is **mandatory** — this is what enables:
-- Epic detection by the `/flo` skill
-- Story extraction for sequential processing
-- Progress tracking via checked/unchecked items
-
-### 2.1 Build Ticket Content
-Compile research into a well-structured ticket. The issue MUST include all three of the following sections:
-
-**Detailed Description** — Clear, thorough explanation of what needs to be done and why. Include:
-- Root cause analysis (bugs) or approach rationale (features)
-- Impact and risk factors
-- Affected files (with line numbers), new files, deletions
-- Implementation plan: numbered steps with clear actions, dependencies, decision points
-
-**Acceptance Criteria** — Specific, testable conditions that must be true for this issue to be considered complete. Write as a checklist:
-- [ ] Criterion 1 (e.g., "API returns 200 with valid token")
-- [ ] Criterion 2 (e.g., "Error message shown when input exceeds 255 chars")
-- [ ] ...each criterion must be independently verifiable
-
-**Suggested Test Cases** — Concrete test scenarios covering happy path, edge cases, and error conditions:
-- Test case 1: description, input, expected output
-- Test case 2: description, input, expected output
-- Include unit, integration, and E2E test suggestions as appropriate
-
-### 2.2 Create or Update GitHub Issue
-
-**If issue number was given** (update existing):
-```bash
-gh issue edit <issue-number> --body "<original body + ## Description + ## Acceptance Criteria + ## Suggested Test Cases>"
-gh issue comment <issue-number> --body "Ticket enhanced with description, acceptance criteria, and test cases. Ready for execution."
-```
-
-**If title was given** (create new):
-```bash
-gh issue create --title "<title>" --body "<## Description + ## Acceptance Criteria + ## Suggested Test Cases>"
-```
-Print the new issue URL so the user can see it.
-
-## Phase 3: Execute (default, runs automatically after ticket)
-
-### 3.1 Assign Issue and Update Status
-```bash
-gh issue edit <issue-number> --add-assignee @me
-gh issue edit <issue-number> --add-label "in-progress"
-```
-
-### 3.2 Create Branch
-```bash
-git checkout main && git pull origin main
-git checkout -b <type>/<issue-number>-<short-desc>
-```
-Types: `feature/`, `fix/`, `refactor/`, `docs/`
-
-### 3.3 Implement
-Follow the implementation plan from the ticket. No prompts - execute all steps.
-
-## Phase 4: Testing (MANDATORY GATE)
-
-This is NOT optional. ALL applicable test types must pass for the change type.
-WORKFLOW STOPS HERE until tests pass. No shortcuts. No exceptions.
-
-### 4.1 Write and Run Tests
-Write unit, integration, and E2E tests as appropriate for the change type.
-Follow the project's established test style, runner, and patterns. If no existing tests or test guidance is present, choose the best options for the project's language and stack, taking compatibility with existing dependencies into account.
-
-### 4.2 Test Auto-Fix Loop
-If any tests fail, enter the auto-fix loop (max 3 retries OR 10 minutes):
-1. Run all tests
-2. If ALL pass -> proceed to simplification
-3. If ANY fail: analyze failure, fix test or implementation code, retry
-4. If retries exhausted -> STOP and report to user
-
-## Phase 4.5: Code Simplification (MANDATORY)
-
-The built-in /simplify command reviews ALL changed code for:
-- Reuse opportunities and code quality
-- Efficiency improvements
-- Consistency with existing codebase patterns
-- Preserves ALL functionality - no behavior changes
-
-If /simplify makes changes -> re-run tests to confirm nothing broke.
-If re-tests fail -> revert changes, proceed with original code.
-
-## Phase 5: Commit and PR (only after tests pass)
-
-### 5.1 Commit
-```bash
-git add <specific files>
-git commit -m "type(scope): description
-
-Closes #<issue-number>
-
-Co-Authored-By: Claude <noreply@anthropic.com>"
-```
-
-### 5.2 Create PR
-```bash
-git push -u origin <branch-name>
-gh pr create --title "type(scope): description" --body "## Summary
-<brief description>
-
-## Changes
-<bullet list>
-
-## Testing
-- [x] Unit tests pass
-- [x] Integration tests pass
-- [x] E2E tests pass
-- [ ] Manual testing done
-
-Closes #<issue-number>"
-```
-
-### 5.3 Update Issue Status
-```bash
-gh issue edit <issue-number> --remove-label "in-progress" --add-label "ready-for-review"
-gh issue comment <issue-number> --body "PR created: <pr-url>"
-```
-
-## Epic Handling
-
-### Detecting Epics
-
-An issue is an **epic** if:
-1. It has the `epic` label, OR
-2. Its body contains `## Stories` or `## Tasks` sections, OR
-3. It has linked child issues (via `- [ ] #123` checklist format)
-
-### Epic Processing Flow
-
-1. DETECT EPIC - Check labels, parse body for ## Stories / ## Tasks, extract issue references
-2. LIST ALL STORIES - Extract from checklist, order top-to-bottom as listed
-3. SEQUENTIAL PROCESSING - For each story:
-   a. Run full /flo workflow (research -> ticket -> implement -> test -> PR)
-   b. After PR is created, **check off the story** in the epic body
-   c. Move to the next unchecked story
-4. COMPLETION - All stories checked off, epic marked as ready-for-review
-
-ONE STORY AT A TIME - NO PARALLEL STORY EXECUTION.
-Each story must complete (PR created) before starting next.
-
-### Epic Checklist Tracking (MANDATORY)
-
-After each story's PR is created, update the epic body to check off that story:
-
-```bash
-# 1. Fetch current epic body
-EPIC_BODY=$(gh issue view <epic-number> --json body -q '.body')
-
-# 2. Replace "- [ ] #<story-number>" with "- [x] #<story-number>"
-UPDATED_BODY=$(echo "$EPIC_BODY" | sed 's/- \[ \] #<story-number>/- [x] #<story-number>/')
-
-# 3. Update the epic
-gh issue edit <epic-number> --body "$UPDATED_BODY"
-
-# 4. Comment on the epic with progress
-gh issue comment <epic-number> --body "✅ Story #<story-number> completed — PR: <pr-url>"
-```
-
-This applies to ALL epics, regardless of how they were created:
-- Epics created by `/flo -t` complexity promotion
-- Epics created manually by users
-- Epics detected from existing issues
-
-The checklist state (`[ ]` vs `[x]`) is the **single source of truth** for epic progress.
-
-### Epic Detection Code
-
-```javascript
-function isEpic(issue) {
-  // Label-based detection (case-insensitive)
-  const epicLabels = ['epic', 'tracking', 'parent', 'umbrella'];
-  if (issue.labels?.some(l => epicLabels.includes(l.name.toLowerCase()))) return true;
-  // Section-based detection
-  if (issue.body?.includes('## Stories') || issue.body?.includes('## Tasks')) return true;
-  // Checklist-linked issues: - [ ] #123 or - [x] #123
-  if (/- \[[ x]\] #\d+/.test(issue.body)) return true;
-  // Numbered issue references: 1. #123
-  if (/\d+\.\s+#\d+/.test(issue.body)) return true;
-  // GitHub sub-issues API
-  if (issue.subIssues?.length > 0) return true;
-  return false;
-}
-
-function extractStories(epicBody) {
-  const stories = [];
-  // Checklist format: - [ ] #123
-  const checklistPattern = /- \[[ ]\] #(\d+)/g;
-  let match;
-  while ((match = checklistPattern.exec(epicBody)) !== null) {
-    stories.push(parseInt(match[1]));
-  }
-  // Numbered format: 1. #123
-  if (stories.length === 0) {
-    const numberedPattern = /\d+\.\s+#(\d+)/g;
-    while ((match = numberedPattern.exec(epicBody)) !== null) {
-      stories.push(parseInt(match[1]));
-    }
-  }
-  return stories;
-}
-```
-
-## Parse Arguments
-
-```javascript
-const args = "$ARGUMENTS".trim().split(/\s+/);
-let workflowMode = "full";    // full, ticket, research
-let execMode = "normal";      // normal (default), swarm, hive
-let issueNumber = null;
-let titleWords = [];
-
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-
-  // Workflow mode (what to do)
-  if (arg === "-t" || arg === "--ticket") {
-    workflowMode = "ticket";
-  } else if (arg === "-r" || arg === "--research") {
-    workflowMode = "research";
-  }
-
-  // Execution mode (how to do it)
-  else if (arg === "-s" || arg === "--swarm") {
-    execMode = "swarm";
-  } else if (arg === "-h" || arg === "--hive") {
-    execMode = "hive";
-  } else if (arg === "-n" || arg === "--normal") {
-    execMode = "normal";
-  }
-
-  // Issue number or title text
-  else if (/^\d+$/.test(arg)) {
-    issueNumber = arg;
-  } else {
-    // Non-flag, non-numeric argument — collect as title words
-    titleWords.push(arg);
-  }
-}
-
-// In ticket mode, a title can be given instead of an issue number
-let ticketTitle = titleWords.join(" ");
-if (!issueNumber && !ticketTitle) {
-  throw new Error("Issue number or title required. Usage: /flo <issue-number | title>");
-}
-if (!issueNumber && workflowMode !== "ticket") {
-  throw new Error("Issue number required for full/research mode. Use -t for new tickets.");
-}
-
-// Log execution mode to prevent silent skipping
-console.log("Execution mode: " + execMode.toUpperCase());
-if (execMode === "swarm") {
-  console.log("SWARM MODE: Will spawn agents via Task tool. Do NOT skip this.");
-}
-console.log("TESTING: Unit + Integration + E2E tests REQUIRED before PR.");
-console.log("SIMPLIFY: /simplify command runs on changed code before PR.");
-```
-
-## Execution Flow
-
-### Workflow Modes (what to do)
-
-| Mode | Command | Steps | Stops After |
-|------|---------|-------|-------------|
-| **Full** (default) | `/flo 123` | Research -> Ticket -> Implement -> Test -> Simplify -> PR | PR created |
-| **Epic** | `/flo 42` (epic) | For each story: Full workflow sequentially | All story PRs created |
-| **Ticket** | `/flo -t 123` | Research -> Ticket | Issue updated |
-| **Research** | `/flo -r 123` | Research | Findings output |
-
-### Execution Modes (how to do it)
-
-| Mode | Flag | Description | When to Use |
-|------|------|-------------|-------------|
-| **Normal** (DEFAULT) | `-n`, `--normal` | Single Claude, no agents | Default for most tasks |
-| **Swarm** | `-s`, `--swarm` | Multi-agent via Task tool | Complex multi-file changes |
-| **Hive-Mind** | `-h`, `--hive` | Consensus-based coordination | Architecture decisions, tradeoffs |
-
-## Execution Mode Details
-
-### SWARM Mode (-s, --swarm)
-
-When swarm is requested, you MUST use the Task tool to spawn agents. No exceptions.
-
-**Swarm spawns these agents via Task tool:**
-- `researcher` - Analyzes issue, searches memory, finds patterns
-- `coder` - Implements changes following plan
-- `tester` - Writes and runs tests
-- `/simplify` - Built-in command that reviews changed code before PR
-- `reviewer` - Reviews code before PR
-
-**Swarm execution pattern:**
-```javascript
-// 1. Create task list FIRST
-TaskCreate({ subject: "Research issue #123", ... })
-TaskCreate({ subject: "Implement changes", ... })
-TaskCreate({ subject: "Test implementation", ... })
-TaskCreate({ subject: "Run /simplify on changed files", ... })
-TaskCreate({ subject: "Review and PR", ... })
-
-// 2. Init swarm
-Bash("npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
-
-// 3. Spawn agents with Task tool (run_in_background: true)
-Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
-Task({ prompt: "...", subagent_type: "coder", run_in_background: true })
-
-// 4. Wait for results, synthesize, continue
-```
-
-### HIVE-MIND Mode (-h, --hive)
-
-Use for consensus-based decisions:
-- Architecture choices
-- Approach tradeoffs
-- Design decisions with multiple valid options
-
-### NORMAL Mode (Default)
-
-Single Claude execution without spawning sub-agents.
-- Still uses Task tool for tracking
-- Still creates tasks for visibility
-- Post-task neural learning hooks still fire
-- Just doesn't spawn multiple agents
-
----
-
-**Full mode executes without prompts.** It will:
-1. Research the issue and codebase
-2. Enhance the GitHub issue with implementation plan
-3. Assign issue to self, add "in-progress" label
-4. Create branch, implement, test
-5. Run /simplify on changed code, re-test if changes made
-6. Commit, create PR, update issue status
-7. Store learnings
+---
+name: flo
+description: MoFlo ticket workflow - analyze and execute GitHub issues
+arguments: "[options] <issue-number | title>"
+---
+
+# /flo - MoFlo Ticket Workflow
+
+Research, create tickets for, and execute GitHub issues automatically.
+
+**Arguments:** $ARGUMENTS
+
+## Usage
+
+```
+/flo <issue-number>                   # Full workflow in NORMAL mode (default)
+/flo -t <issue-number>                # Ticket only: research and update ticket, then STOP
+/flo -t <title>                       # Create a NEW ticket with description, acceptance criteria, test cases
+/flo --ticket <issue-number|title>    # Same as -t
+/flo -r <issue-number>                # Research only: analyze issue, output findings
+/flo --research <issue-number>        # Same as -r
+```
+
+Also available as `/fl` (shorthand alias).
+
+### Execution Mode (how work is done)
+
+```
+/flo 123                              # NORMAL mode (default) - single-agent execution
+/flo -s 123                           # SWARM mode - multi-agent coordination
+/flo --swarm 123                      # Same as -s
+/flo -h 123                           # HIVE-MIND mode - consensus-based coordination
+/flo --hive 123                       # Same as -h
+/flo -n 123                           # NORMAL mode - single Claude, no agents
+/flo --normal 123                     # Same as -n
+```
+
+### Epic Handling
+
+```
+/flo 42                               # If #42 is an epic, processes all stories sequentially
+```
+
+**Epic Detection:** An issue is automatically detected as an epic if ANY of these are true:
+- Has a label matching: `epic`, `tracking`, `parent`, or `umbrella` (case-insensitive)
+- Body contains `## Stories` or `## Tasks` sections
+- Body has checklist-linked issues: `- [ ] #123`
+- Body has numbered issue references: `1. #123`
+- The issue has GitHub sub-issues (via `subIssues` API field)
+
+**Sequential Processing:** When an epic is selected:
+1. List all child stories/tasks (from checklist or linked issues)
+2. Process each story **one at a time** in order
+3. Each story goes through the full workflow (research -> ticket -> implement -> test -> PR)
+4. After each story's PR is created, move to the next story
+5. Continue until all stories are complete
+
+### Combined Examples
+
+```
+/flo 123                              # Normal + full workflow (default) - includes ALL tests
+/flo 42                               # If #42 is epic, processes stories sequentially
+/flo -s 123                           # Swarm + full workflow (multi-agent coordination)
+/flo -t 123                           # Normal + ticket only (no implementation)
+/flo -h -t 123                        # Hive-mind + ticket only
+/flo -s -r 123                        # Swarm + research only
+/flo --swarm --ticket 123             # Explicit swarm + ticket only
+/flo -n 123                           # Normal (explicit, same as default)
+```
+
+## NORMAL MODE IS THE DEFAULT
+
+By default, /flo runs in NORMAL mode — single-agent execution without
+spawning sub-agents. This is efficient for most tasks.
+
+Use `-s`/`--swarm` for multi-agent coordination when the task warrants it.
+Use `-h`/`--hive` for consensus-based coordination on architecture decisions.
+
+POST-TASK NEURAL LEARNING ALWAYS RUNS regardless of execution mode.
+The hooks system collects learnings after every task completion — normal,
+swarm, or hive-mind.
+
+## COMPREHENSIVE TESTING REQUIREMENT
+
+ALL tests MUST pass BEFORE PR creation - NO EXCEPTIONS.
+- Unit Tests: MANDATORY for all new/modified code
+- Integration Tests: MANDATORY for API endpoints and services
+- E2E Tests: MANDATORY for user-facing features
+PR CANNOT BE CREATED until all relevant tests pass.
+
+## Workflow Overview
+
+```
+Research -> Ticket -> Execute -> Testing -> Simplify -> PR+Done
+
+Research:    Fetch issue, search memory, read guidance, find files
+Ticket:      Create or update GitHub issue with description, acceptance criteria, test cases
+Execute:     Assign self, create branch, implement changes
+Testing:     Unit + Integration + E2E tests (ALL MUST PASS - gate)
+Simplify:    Run /simplify on changed code (gate - must run before PR)
+PR+Done:     Create PR, update issue status, store learnings
+```
+
+### Workflow Gates
+
+| Gate | Requirement | Blocked Action |
+|------|-------------|----------------|
+| **Testing Gate** | Unit + Integration + E2E must pass | PR creation |
+| **Simplification Gate** | /simplify must run on changed files | PR creation |
+
+### Execution Mode (applies to all phases)
+
+| Mode | Description |
+|------|-------------|
+| **NORMAL** (default) | Single Claude execution. Efficient for most tasks. |
+| **SWARM** (-s) | Multi-agent via Task tool: researcher, coder, tester, reviewer |
+| **HIVE-MIND** (-h) | Consensus-based coordination for architecture decisions |
+
+## Phase 1: Research (-r or default first step)
+
+### 1.1 Fetch Issue Details
+```bash
+gh issue view <issue-number> --json number,title,body,labels,state,assignees,comments,milestone
+```
+
+### 1.2 Check Ticket Status
+Look for `## Acceptance Criteria` marker in issue body.
+- **If present**: Ticket already enhanced, skip to execute or confirm
+- **If absent**: Proceed with research and ticket update
+
+### 1.3 Search Memory FIRST
+ALWAYS search memory BEFORE reading guidance or docs files.
+Memory has file paths, context, and patterns - often all you need.
+Only read guidance files if memory search returns zero relevant results.
+
+```bash
+npx flo memory search --query "<issue title keywords>" --namespace patterns
+npx flo memory search --query "<domain keywords>" --namespace guidance
+```
+
+Or via MCP: `mcp__moflo__memory_search`
+
+### 1.4 Read Guidance Docs (ONLY if memory insufficient)
+**Only if memory search returned < 3 relevant results**, read guidance files:
+- Bug -> testing patterns, error handling
+- Feature -> domain model, architecture
+- UI -> frontend patterns, components
+
+### 1.5 Research Codebase
+Use Task tool with Explore agent to find:
+- Affected files and their current state
+- Related code and dependencies
+- Existing patterns to follow
+- Test coverage gaps
+
+## Phase 2: Ticket (-t creates or updates a ticket)
+
+When given an issue number, `-t` enhances the existing ticket. When given a title (non-numeric argument), `-t` creates a new GitHub issue. Either way, the ticket MUST include all three of the following sections.
+
+### 2.0 Complexity Assessment (MANDATORY before building ticket)
+
+After research, assess the complexity of the work. This determines whether the issue stays as a single ticket or gets promoted to an epic with sub-issues.
+
+**Complexity Signals — count how many apply:**
+
+| Signal | Weight | Example |
+|--------|--------|---------|
+| Multiple files changed (5+) | +2 | Touches models, API, tests, docs, config |
+| New module or package | +2 | Requires new directory structure |
+| Cross-cutting concern | +2 | Auth, logging, error handling across layers |
+| Database/schema changes | +2 | Migrations, new tables, index changes |
+| Multiple independent work streams | +3 | Frontend + backend + infra changes |
+| External API integration | +1 | Third-party service, webhook, OAuth |
+| Breaking change / migration | +2 | Requires deprecation, data migration |
+| Significant test surface | +1 | Needs 10+ new test cases across categories |
+| Security implications | +1 | Authentication, authorization, input validation |
+| UI + backend changes together | +2 | Full-stack feature spanning layers |
+
+**Complexity Thresholds:**
+
+| Score | Classification | Action |
+|-------|---------------|--------|
+| 0–3 | **Simple** | Single ticket — proceed normally |
+| 4–6 | **Moderate** | Single ticket — flag in description that it may benefit from splitting |
+| 7+ | **Complex** | **PROMOTE TO EPIC** — decompose into sub-issues |
+
+**When promoting to epic:**
+
+1. Decompose the work into 2–6 independent, shippable stories
+2. Each story should be completable in a single PR
+3. Stories should have clear boundaries (one concern per story)
+4. Order stories by dependency (independent ones first)
+5. Create each story as a GitHub issue with its own Description, Acceptance Criteria, and Test Cases
+6. Create or convert the parent issue into an epic with a `## Stories` checklist
+
+```javascript
+// Complexity assessment pseudocode
+function assessComplexity(research) {
+  let score = 0;
+  if (research.affectedFiles.length >= 5) score += 2;
+  if (research.requiresNewModule) score += 2;
+  if (research.crossCutting) score += 2;
+  if (research.schemaChanges) score += 2;
+  if (research.independentWorkStreams >= 2) score += 3;
+  if (research.externalAPIs) score += 1;
+  if (research.breakingChanges) score += 2;
+  if (research.estimatedTestCases >= 10) score += 1;
+  if (research.securityImplications) score += 1;
+  if (research.fullStack) score += 2;
+  return score;
+}
+```
+
+### 2.0.1 Epic Decomposition (when score >= 7)
+
+When complexity warrants an epic, decompose into stories:
+
+```bash
+# Step 1: Create each sub-issue
+gh issue create --title "Story: <story-title>" --body "<## Description + ## Acceptance Criteria + ## Suggested Test Cases>" --label "story"
+# Capture the new issue number from output
+
+# Step 2: Repeat for all stories (2-6 stories typically)
+
+# Step 3: Build the epic body with checklist referencing ALL story issue numbers
+# Step 4: If updating an existing issue, convert it to epic:
+gh issue edit <parent-number> --add-label "epic" --body "<epic body with ## Stories checklist>"
+
+# Step 5: If creating new, create the epic:
+gh issue create --title "Epic: <title>" --label "epic" --body "<epic body>"
+```
+
+**Epic body format (MANDATORY — this is how tracking works):**
+
+```markdown
+## Overview
+<High-level description of the epic goal>
+
+## Stories
+
+- [ ] #<story-1-number> <story-1-title>
+- [ ] #<story-2-number> <story-2-title>
+- [ ] #<story-3-number> <story-3-title>
+
+## Complexity Assessment
+Score: <N>/20 — <Simple|Moderate|Complex>
+Signals: <list of signals that triggered>
+```
+
+The `## Stories` checklist with `- [ ] #<number>` format is **mandatory** — this is what enables:
+- Epic detection by the `/flo` skill
+- Story extraction for sequential processing
+- Progress tracking via checked/unchecked items
+
+### 2.1 Build Ticket Content
+Compile research into a well-structured ticket. The issue MUST include all three of the following sections:
+
+**Detailed Description** — Clear, thorough explanation of what needs to be done and why. Include:
+- Root cause analysis (bugs) or approach rationale (features)
+- Impact and risk factors
+- Affected files (with line numbers), new files, deletions
+- Implementation plan: numbered steps with clear actions, dependencies, decision points
+
+**Acceptance Criteria** — Specific, testable conditions that must be true for this issue to be considered complete. Write as a checklist:
+- [ ] Criterion 1 (e.g., "API returns 200 with valid token")
+- [ ] Criterion 2 (e.g., "Error message shown when input exceeds 255 chars")
+- [ ] ...each criterion must be independently verifiable
+
+**Suggested Test Cases** — Concrete test scenarios covering happy path, edge cases, and error conditions:
+- Test case 1: description, input, expected output
+- Test case 2: description, input, expected output
+- Include unit, integration, and E2E test suggestions as appropriate
+
+### 2.2 Create or Update GitHub Issue
+
+**If issue number was given** (update existing):
+```bash
+gh issue edit <issue-number> --body "<original body + ## Description + ## Acceptance Criteria + ## Suggested Test Cases>"
+gh issue comment <issue-number> --body "Ticket enhanced with description, acceptance criteria, and test cases. Ready for execution."
+```
+
+**If title was given** (create new):
+```bash
+gh issue create --title "<title>" --body "<## Description + ## Acceptance Criteria + ## Suggested Test Cases>"
+```
+Print the new issue URL so the user can see it.
+
+## Phase 3: Execute (default, runs automatically after ticket)
+
+### 3.1 Assign Issue and Update Status
+```bash
+gh issue edit <issue-number> --add-assignee @me
+gh issue edit <issue-number> --add-label "in-progress"
+```
+
+### 3.2 Create Branch
+```bash
+git checkout main && git pull origin main
+git checkout -b <type>/<issue-number>-<short-desc>
+```
+Types: `feature/`, `fix/`, `refactor/`, `docs/`
+
+### 3.3 Implement
+Follow the implementation plan from the ticket. No prompts - execute all steps.
+
+## Phase 4: Testing (MANDATORY GATE)
+
+This is NOT optional. ALL applicable test types must pass for the change type.
+WORKFLOW STOPS HERE until tests pass. No shortcuts. No exceptions.
+
+### 4.1 Write and Run Tests
+Write unit, integration, and E2E tests as appropriate for the change type.
+Follow the project's established test style, runner, and patterns. If no existing tests or test guidance is present, choose the best options for the project's language and stack, taking compatibility with existing dependencies into account.
+
+### 4.2 Test Auto-Fix Loop
+If any tests fail, enter the auto-fix loop (max 3 retries OR 10 minutes):
+1. Run all tests
+2. If ALL pass -> proceed to simplification
+3. If ANY fail: analyze failure, fix test or implementation code, retry
+4. If retries exhausted -> STOP and report to user
+
+## Phase 4.5: Code Simplification (MANDATORY)
+
+The built-in /simplify command reviews ALL changed code for:
+- Reuse opportunities and code quality
+- Efficiency improvements
+- Consistency with existing codebase patterns
+- Preserves ALL functionality - no behavior changes
+
+If /simplify makes changes -> re-run tests to confirm nothing broke.
+If re-tests fail -> revert changes, proceed with original code.
+
+## Phase 5: Commit and PR (only after tests pass)
+
+### 5.1 Commit
+```bash
+git add <specific files>
+git commit -m "type(scope): description
+
+Closes #<issue-number>
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+### 5.2 Create PR
+```bash
+git push -u origin <branch-name>
+gh pr create --title "type(scope): description" --body "## Summary
+<brief description>
+
+## Changes
+<bullet list>
+
+## Testing
+- [x] Unit tests pass
+- [x] Integration tests pass
+- [x] E2E tests pass
+- [ ] Manual testing done
+
+Closes #<issue-number>"
+```
+
+### 5.3 Update Issue Status
+```bash
+gh issue edit <issue-number> --remove-label "in-progress" --add-label "ready-for-review"
+gh issue comment <issue-number> --body "PR created: <pr-url>"
+```
+
+## Epic Handling
+
+### Detecting Epics
+
+An issue is an **epic** if:
+1. It has the `epic` label, OR
+2. Its body contains `## Stories` or `## Tasks` sections, OR
+3. It has linked child issues (via `- [ ] #123` checklist format)
+
+### Epic Processing Flow
+
+1. DETECT EPIC - Check labels, parse body for ## Stories / ## Tasks, extract issue references
+2. LIST ALL STORIES - Extract from checklist, order top-to-bottom as listed
+3. SEQUENTIAL PROCESSING - For each story:
+   a. Run full /flo workflow (research -> ticket -> implement -> test -> PR)
+   b. After PR is created, **check off the story** in the epic body
+   c. Move to the next unchecked story
+4. COMPLETION - All stories checked off, epic marked as ready-for-review
+
+ONE STORY AT A TIME - NO PARALLEL STORY EXECUTION.
+Each story must complete (PR created) before starting next.
+
+### Epic Checklist Tracking (MANDATORY)
+
+After each story's PR is created, update the epic body to check off that story:
+
+```bash
+# 1. Fetch current epic body
+EPIC_BODY=$(gh issue view <epic-number> --json body -q '.body')
+
+# 2. Replace "- [ ] #<story-number>" with "- [x] #<story-number>"
+UPDATED_BODY=$(echo "$EPIC_BODY" | sed 's/- \[ \] #<story-number>/- [x] #<story-number>/')
+
+# 3. Update the epic
+gh issue edit <epic-number> --body "$UPDATED_BODY"
+
+# 4. Comment on the epic with progress
+gh issue comment <epic-number> --body "✅ Story #<story-number> completed — PR: <pr-url>"
+```
+
+This applies to ALL epics, regardless of how they were created:
+- Epics created by `/flo -t` complexity promotion
+- Epics created manually by users
+- Epics detected from existing issues
+
+The checklist state (`[ ]` vs `[x]`) is the **single source of truth** for epic progress.
+
+### Epic Detection Code
+
+```javascript
+function isEpic(issue) {
+  // Label-based detection (case-insensitive)
+  const epicLabels = ['epic', 'tracking', 'parent', 'umbrella'];
+  if (issue.labels?.some(l => epicLabels.includes(l.name.toLowerCase()))) return true;
+  // Section-based detection
+  if (issue.body?.includes('## Stories') || issue.body?.includes('## Tasks')) return true;
+  // Checklist-linked issues: - [ ] #123 or - [x] #123
+  if (/- \[[ x]\] #\d+/.test(issue.body)) return true;
+  // Numbered issue references: 1. #123
+  if (/\d+\.\s+#\d+/.test(issue.body)) return true;
+  // GitHub sub-issues API
+  if (issue.subIssues?.length > 0) return true;
+  return false;
+}
+
+function extractStories(epicBody) {
+  const stories = [];
+  // Checklist format: - [ ] #123
+  const checklistPattern = /- \[[ ]\] #(\d+)/g;
+  let match;
+  while ((match = checklistPattern.exec(epicBody)) !== null) {
+    stories.push(parseInt(match[1]));
+  }
+  // Numbered format: 1. #123
+  if (stories.length === 0) {
+    const numberedPattern = /\d+\.\s+#(\d+)/g;
+    while ((match = numberedPattern.exec(epicBody)) !== null) {
+      stories.push(parseInt(match[1]));
+    }
+  }
+  return stories;
+}
+```
+
+## Parse Arguments
+
+```javascript
+const args = "$ARGUMENTS".trim().split(/\s+/);
+let workflowMode = "full";    // full, ticket, research
+let execMode = "normal";      // normal (default), swarm, hive
+let issueNumber = null;
+let titleWords = [];
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+
+  // Workflow mode (what to do)
+  if (arg === "-t" || arg === "--ticket") {
+    workflowMode = "ticket";
+  } else if (arg === "-r" || arg === "--research") {
+    workflowMode = "research";
+  }
+
+  // Execution mode (how to do it)
+  else if (arg === "-s" || arg === "--swarm") {
+    execMode = "swarm";
+  } else if (arg === "-h" || arg === "--hive") {
+    execMode = "hive";
+  } else if (arg === "-n" || arg === "--normal") {
+    execMode = "normal";
+  }
+
+  // Issue number or title text
+  else if (/^\d+$/.test(arg)) {
+    issueNumber = arg;
+  } else {
+    // Non-flag, non-numeric argument — collect as title words
+    titleWords.push(arg);
+  }
+}
+
+// In ticket mode, a title can be given instead of an issue number
+let ticketTitle = titleWords.join(" ");
+if (!issueNumber && !ticketTitle) {
+  throw new Error("Issue number or title required. Usage: /flo <issue-number | title>");
+}
+if (!issueNumber && workflowMode !== "ticket") {
+  throw new Error("Issue number required for full/research mode. Use -t for new tickets.");
+}
+
+// Log execution mode to prevent silent skipping
+console.log("Execution mode: " + execMode.toUpperCase());
+if (execMode === "swarm") {
+  console.log("SWARM MODE: Will spawn agents via Task tool. Do NOT skip this.");
+}
+console.log("TESTING: Unit + Integration + E2E tests REQUIRED before PR.");
+console.log("SIMPLIFY: /simplify command runs on changed code before PR.");
+```
+
+## Execution Flow
+
+### Workflow Modes (what to do)
+
+| Mode | Command | Steps | Stops After |
+|------|---------|-------|-------------|
+| **Full** (default) | `/flo 123` | Research -> Ticket -> Implement -> Test -> Simplify -> PR | PR created |
+| **Epic** | `/flo 42` (epic) | For each story: Full workflow sequentially | All story PRs created |
+| **Ticket** | `/flo -t 123` | Research -> Ticket | Issue updated |
+| **Research** | `/flo -r 123` | Research | Findings output |
+
+### Execution Modes (how to do it)
+
+| Mode | Flag | Description | When to Use |
+|------|------|-------------|-------------|
+| **Normal** (DEFAULT) | `-n`, `--normal` | Single Claude, no agents | Default for most tasks |
+| **Swarm** | `-s`, `--swarm` | Multi-agent via Task tool | Complex multi-file changes |
+| **Hive-Mind** | `-h`, `--hive` | Consensus-based coordination | Architecture decisions, tradeoffs |
+
+## Execution Mode Details
+
+### SWARM Mode (-s, --swarm)
+
+When swarm is requested, you MUST use the Task tool to spawn agents. No exceptions.
+
+**Swarm spawns these agents via Task tool:**
+- `researcher` - Analyzes issue, searches memory, finds patterns
+- `coder` - Implements changes following plan
+- `tester` - Writes and runs tests
+- `/simplify` - Built-in command that reviews changed code before PR
+- `reviewer` - Reviews code before PR
+
+**Swarm execution pattern:**
+```javascript
+// 1. Create task list FIRST
+TaskCreate({ subject: "Research issue #123", ... })
+TaskCreate({ subject: "Implement changes", ... })
+TaskCreate({ subject: "Test implementation", ... })
+TaskCreate({ subject: "Run /simplify on changed files", ... })
+TaskCreate({ subject: "Review and PR", ... })
+
+// 2. Init swarm
+Bash("npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
+
+// 3. Spawn agents with Task tool (run_in_background: true)
+Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
+Task({ prompt: "...", subagent_type: "coder", run_in_background: true })
+
+// 4. Wait for results, synthesize, continue
+```
+
+### HIVE-MIND Mode (-h, --hive)
+
+Use for consensus-based decisions:
+- Architecture choices
+- Approach tradeoffs
+- Design decisions with multiple valid options
+
+### NORMAL Mode (Default)
+
+Single Claude execution without spawning sub-agents.
+- Still uses Task tool for tracking
+- Still creates tasks for visibility
+- Post-task neural learning hooks still fire
+- Just doesn't spawn multiple agents
+
+---
+
+**Full mode executes without prompts.** It will:
+1. Research the issue and codebase
+2. Enhance the GitHub issue with implementation plan
+3. Assign issue to self, add "in-progress" label
+4. Create branch, implement, test
+5. Run /simplify on changed code, re-test if changes made
+6. Commit, create PR, update issue status
+7. Store learnings