Superflow v4.4.0 — Parallel Sprints + Stub Prevention

What's New

Sprint-Level Parallel Execution

Independent sprints now run concurrently. The plan includes files: and depends_on: per sprint — Phase 2 builds a dependency graph and groups sprints into waves. Each sprint still runs the full flow (implement → review → PAR → docs → ship) in its own worktree.

Plan: 6 sprints → Wave 1: [1,2,6] parallel → Wave 2: [3,4,5] parallel
Result: ~2x speedup

Works together with existing task-level parallelism within each sprint.

Stub Sprint Prevention (postmortem fix)

Root cause from a real failure: Sprint 5 plan specified 5 tasks but implementer delivered a 60-line stub doing 1. Reviewers approved because code compiled and tests passed.

Three fixes:

• Code reviewer: new focus area "Plan completeness" — compares implementation against plan, flags when 60 lines implements what a sibling did in 400
• Product reviewer: completeness check now includes plan-to-code validation
• Per-Sprint Flow: verbatim sprint task list injected into implementer prompt — prevents context compaction from erasing plan details

Actionable Phase 0 Summary

• Critical findings highlighted with fix suggestions
• Tech debt strategy explained: "findings saved, addressed progressively when features touch affected modules"
• Sprint 0 offered for critical issues before feature work

Install

From source (recommended):

git clone https://github.com/egerev/superflow.git
ln -s $(pwd)/superflow ~/.claude/skills/superflow

From .skill package:

unzip superflow.skill -d ~/.claude/skills/

Then run /superflow in Claude Code.

Superflow v4.3.0 — Codebase Hygiene Pipeline

What's New

Codebase Hygiene Pipeline

AI agents are prone to three specific code quality issues: duplicating existing code, redefining types that already exist (especially auto-generated ones), and leaving dead code after refactoring. v4.3.0 adds explicit checks for all three at every level of the pipeline:

• Implementer — prevention rules: search for existing code/types before writing new, clean up dead code after refactoring
• Per-sprint reviewer — three new focus areas (#8 duplication, #9 type redefinition, #10 dead code) with concrete detection guidance
• Holistic review — mandatory cross-sprint checks: catches duplication and dead code that spans sprint boundaries
• Phase 0 diagnosis — Code Quality agent now detects type redefinition during initial project audit

Per-Sprint Documentation Updates

New Stage 5 "Docs" in Phase 2 — dispatches standard-doc-writer after PAR to update CLAUDE.md and llms.txt based on sprint diff. Skips automatically if nothing materially changed. Phase 2 sprints now have 6 stages (was 5).

Fixed

• Phase 0 re-trigger loop on zsh: marker detection command used { } brace grouping which breaks in zsh — replaced with ( ) subshell
• Phase 0 auto-commit: onboarding artifacts now commit automatically (no user confirmation) and propagate to main when on a feature branch

Install

From source (recommended):

git clone https://github.com/egerev/superflow.git
ln -s $(pwd)/superflow ~/.claude/skills/superflow

From .skill package:

# Download superflow.skill from this release
unzip superflow.skill -d ~/.claude/skills/

Then run /superflow in Claude Code.

Superflow v4.2.0

What's New

Features

• Tech debt cross-reference: After writing spec, cross-references context.tech_debt with modified files and suggests bundling related refactoring
• Startup banner: Visual status display with provider, Telegram, mode, and phase info

Fixed

• Phase 0 reliability: Marker detection checks main branch as fallback; completion prompts to commit onboarding artifacts
• Phase 3 merge guard: Compaction-safe enforcement rule prevents local git merge fallback
• Approval gate visibility: Brief and plan displayed inline before asking for approval
• Reasoning tiers aligned: All implementers use sonnet; expert panel uses opus/high effort

Install

From source (recommended):

git clone https://github.com/egerev/superflow.git
ln -s $(pwd)/superflow ~/.claude/skills/superflow

From .skill package:

# Download superflow.skill from this release
unzip superflow.skill -d ~/.claude/skills/

Then run /superflow in Claude Code.

v4.1.0 — Pure Markdown

Removed Python supervisor and all Python code. Superflow is now a pure Markdown skill — zero dependencies, install = git clone + ln -s.

Removed: supervisor.py, launcher.py, checkpoint.py, parallel.py, replanner.py, notifications.py, bin/superflow-supervisor, queue.py, planner.py, all tests (~12,500 lines deleted)

Why: Subagent-based Phase 2 works perfectly — proven on 9+ sprints. The Python supervisor was fragile and added complexity without proportional value.

Full changelog: CHANGELOG.md

v4.0.2 — Marker fix

Fixes

• Phase 0 markers: doc generation prompts now require marker as checklist item. Stage 4 validates with grep before reporting. Fixes repeated Phase 0 on every /superflow run.

v4.0.1 — Timeout, Security, Frontend Testing

Fixes

• Complexity-based timeout: simple=100min, medium=200min, complex=300min (was 30min for all)
• Retry with context: retry prompt includes "check git diff, continue where stopped"
• Security: path validation for queue metadata (prevents ../ traversal)
• Frontend testing: Playwright integration in Phase 2 for UI sprints (frontend: true)

448 tests (was 430).

v4.0.0 — Workflow Evolution

Superflow v4.0.0 — Workflow Evolution

Major release: 5 new capabilities across 9 sprints, 430 tests (was 333).

Expert Panel Brainstorming

Phase 1 brainstorming overhauled: 3-4 parallel expert agents (Product GM, Staff Engineer, UX/Workflow, Domain Expert) debate independently, orchestrator synthesizes into a Board Memo with consensus, disagreements, risks, and decisions needed. Optional Devil's Advocate challenge. Round-trips reduced from 7 to 2-3.

Autonomy Charter

New artifact generated at end of Phase 1 — single source of truth for intent. YAML frontmatter (goal, non-negotiables, stop conditions, governance mode) + human-readable body. Injected into sprint prompts, reviewer prompts, and replanner.

Adaptive Governance

Three modes: light (collapsed docs, single reviewer), standard (full ceremony), critical (extended debate, threat model). Auto-suggested based on novelty/blast radius/ambiguity. Review tiering: single Technical reviewer for light/simple sprints, conditional holistic review.

Telegram Control Plane

• Full coverage: updates at every Phase 0/1/3 stage transition
• Document attachments at approval gates (review from phone)
• Commands: /status, /skip N, /hold, /resume, /merge, /log
• Hold-request sidecar mechanism for pausing supervisor between sprints

Observability

• subprocess.Popen replaces subprocess.run — 15s poll loop fixes stale heartbeat (was frozen 20+ min during sprint execution)
• Intra-sprint progress: agent writes .superflow/sprint-progress.json, supervisor relays step changes
• Progress digest every N sprints
• Typed blocker escalation with recommended action
• Merge reminder at completion

Cross-Phase Data Flow

• State schema: brief_file, charter_file, completion_data_file, governance_mode
• Merge-update pattern (preserves context.* across phase transitions)
• Structured completion-data.json for Phase 3
• Phase 0 tech_debt propagated to Phase 1 context
• Product brief injected into sprint sessions

Bug Fixes

• Supervisor binary path resolved from skill directory (was repo_root — failed in other projects)

Stats

• 97 new tests (333 → 430)
• 9 sprints, all merged sequentially with conflict resolution
• Files changed: supervisor.py, planner.py, queue.py, launcher.py, notifications.py, phase1-discovery.md, phase2-execution.md, phase3-merge.md, supervisor-sprint-prompt.md, superflow-enforcement.md, + 12 more

v3.5.0 — Auto-Supervisor

What's New

Auto-launch supervisor from Phase 1

Say "go" after plan approval — Superflow automatically generates a sprint queue, launches the supervisor in background, and enters dashboard mode. No manual CLI commands needed.

You: "go"
Agent: → generates queue → launches supervisor
Agent: "Supervisor running (PID 12345). 4 sprints queued."

Dashboard Mode

Monitor the background supervisor with interactive commands:

Command	Action
status	Show supervisor PID, current sprint, heartbeat
log	Show last 50 lines of supervisor log
stop	Stop supervisor (graceful shutdown)
restart	Stop + recover crashed sprints + relaunch
skip N	Skip a sprint (writes sidecar request)
merge	Transition to Phase 3 when all sprints done

Plan-to-Queue Generator

Markdown plans are automatically parsed into sprint queues with:

• All heading formats: ## Sprint N: Title, ## Sprint N — Title, ## Sprint N
• Dependency validation and cycle detection (topological sort)
• SHA-256 content hash for freshness checks

Security Hardening

• Path traversal protection in build_prompt() and SprintQueue.load()
• Two-tier environment policy: supervisor gets full env, sprint subprocesses get 19 sensitive keys filtered
• Telegram credentials via env vars only (CLI flags removed — no more tokens in shell history)

Session Reconnection

New sessions detect running/crashed/finished supervisors and resume appropriately:

• Running → enter dashboard mode
• Crashed → offer restart (resume + relaunch)
• Finished → show summary, offer merge

Stats

• New modules: lib/planner.py (220 LOC), lib/launcher.py (334 LOC)
• Tests: 235 → 333 (+98 new tests)
• Lines added: ~3,150
• PRs: #44, #45, #46, #47, #48

Full Changelog

v3.4.0...v3.5.0

v3.2.0

Enforcement Hardening, Phase 0 Improvements, Workflow Discipline

Supervisor Enforcement Hardening (PR #34)

• Validation gates: PAR evidence, sprint summary, evidence verdicts
• Baseline test gate with heuristic detection (Python/JS/Ruby/Go/Elixir)
• PAR retry gate (separate from general retries)
• Holistic review dispatch: 4 parallel reviewers, retry/fix cycle, evidence emission
• Milestone checkpoints for fine-grained crash recovery
• 16 notification event types (up from 11)
• Milestone-aware resume, preflight checks, PR verification
• Default branch detection (no longer hardcoded to main)

Phase 0 Improvements (PR #37)

• Interactive onboarding via AskUserQuestion mini-interview
• Greenfield path (G1-G6) with stack scaffolding templates
• State management via .superflow-state.json across all phases
• Stage/todo structure with TaskCreate/TaskUpdate progress tracking
• Proposal gate, hooks, /verify skill

Workflow Discipline (PR #36)

• Session recovery check in startup checklist
• Test execution discipline (one process, mandatory timeout, no retry loops)
• Commit-before-review rule (Codex sees only committed HEAD)
• Worktree-before-merge (exit worktree before merge to prevent CWD death)

Stats

• 228 tests (up from 149)
• lib/supervisor.py: 1733 lines (up from 743)
• 16 notification event types (up from 11)

Full changelog: https://github.com/egerev/superflow/blob/main/CHANGELOG.md

v3.1.0: Reasoning Tiers & Unified Review

Reasoning Tiers & Unified Review

Added

• Reasoning Tier System — three tiers (deep/standard/fast) with explicit effort frontmatter for Claude agents and -c model_reasoning_effort for Codex
• 12 agent definition files (agents/) — native Claude Code subagent .md files with YAML frontmatter
• 3 Codex-optimized prompts (prompts/codex/) — OpenAI Markdown+XML style
• Unified Review — merged Internal Review + PAR into single 4-agent parallel review (2 Claude + 2 Codex)
• Adaptive Implementation — sprint complexity tags drive model selection (sonnet/opus)
• Codex audit agent in Phase 0 (5th parallel agent)
• Final Holistic Review expanded to 4 agents
• Agent deployment in startup checklist for pre-v3.1 projects

Changed

• Phase 2: 11 → 10 steps (Internal Review + PAR collapsed)
• Phase 0: 10 → 11 steps (new Step 1: deploy agent definitions)
• Supervisor: 4-verdict PAR parsing, complexity extraction, reasoning tier placeholders
• 132 tests (130 existing + 2 new)

Removed

• ultrathink keyword from all subagent prompts (confirmed no-op via testing)

Research Findings

• ultrathink in subagent prompts does NOT work — CLI-level keyword only
• Agent tool does NOT have effort parameter — use .md frontmatter in ~/.claude/agents/
• Codex -c model_reasoning_effort works per-invocation (verified)