Flow-Next Token-Optimized Development Specification

[clairernovotny]

Flow-Next Token-Optimized Development Specification

Complete End-to-End System Design

---

Table of Contents

1. Executive Summary
2. System Overview
3. Resource Inventory
4. Phase 1: Interview
5. Phase 2: Plan
6. Phase 3: Work
7. Phase 4: Review
8. Local Model Infrastructure
9. Multi-Source Orchestration
10. Configuration Reference
11. Implementation Roadmap
12. Appendices

---

1. Executive Summary

1.1 The Problem

Flow-next's Ralph loops burn through premium model quotas (Codex 5.2, Opus 4.5) in 2 days instead of lasting a full week. Token consumption occurs across all phases:

Phase	Current Token Burn	Primary Waste
Interview	Low (human-paced)	None significant
Plan	Medium (scout parallelism)	Redundant codebase scanning
Work	High (implementation)	Full context on every task
Review	Very High	Re-reviewing unchanged code, verbose prompts

1.2 The Solution

Deploy GLM-4.7-Flash (59.2% SWE-Bench) locally to handle preprocessing across all phases while premium models (Opus 4.5, Codex 5.2, Gemini 3 Pro) make final decisions via multi-source quota pooling.

1.3 Key Principles

1. Premium models always make final decisions — No quality compromise
2. Local handles grunt work — Pre-screening, classification, context preparation
3. Multi-source pooling — 4 premium quota pools (OpenAI, Claude, Copilot, Antigravity)
4. No lossy compression — Full context for security/complex reviews
5. Phase-appropriate optimization — Each phase optimized differently

1.4 Expected Outcomes

Metric	Current	Target
Weekly quota duration	2 days	7+ days
Premium calls per task	2-4	0.3-0.5
Review quality	100%	100% (unchanged)
Local pre-screening catch rate	0%	60-80%

---

2. System Overview

2.1 End-to-End Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         FLOW-NEXT OPTIMIZED PIPELINE                         │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 1: INTERVIEW                                                          │
│ /flow-next:interview                                                        │
│                                                                             │
│ Human-paced, low token burn                                                 │
│ Local: Question generation, spec drafting                                   │
│ Premium: Complex decision trees (when needed)                               │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 2: PLAN                                                               │
│ /flow-next:plan                                                             │
│                                                                             │
│ Scout parallelism, moderate token burn                                      │
│ Local: repo-scout, practice-scout, docs-scout (GLM-4.7-Flash)              │
│ Premium: Epic spec writing, architectural decisions                         │
│ Optimization: Scout result caching, incremental updates                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 3: WORK                                                               │
│ /flow-next:work                                                             │
│                                                                             │
│ Implementation, high token burn                                             │
│ Local: Worker pre-anchor summaries, implementation assistance               │
│ Premium: Complex implementation decisions, unfamiliar patterns              │
│ Optimization: Task-scoped context, memory system                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 4: REVIEW                                                             │
│ /flow-next:impl-review, /flow-next:plan-review                              │
│                                                                             │
│ Verification, very high token burn                                          │
│ Local: Pre-screening, fingerprinting, classification                        │
│ Premium: Final SHIP/NEEDS_WORK judgment                                     │
│ Optimization: Multi-source routing, lean prompts                            │
└─────────────────────────────────────────────────────────────────────────────┘

2.2 Model Allocation by Phase

Phase	Local Model	Role	Premium Model	Role
Interview	GLM-4.7-Flash	Question drafting	Opus 4.5	Complex decisions
Plan	GLM-4.7-Flash	Scout agents	Opus 4.5	Epic spec review
Work	GLM-4.7-Flash	Re-anchor, assistance	Opus 4.5 / Codex 5.2	Implementation
Review	GLM-4.7-Flash	Pre-screen, classify	Codex 5.2 / Opus 4.5	Final verdict

2.3 Data Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                              STATE MANAGEMENT                                │
└─────────────────────────────────────────────────────────────────────────────┘

.flow/
├── epics/                    # Epic metadata (JSON)
├── tasks/                    # Task metadata (JSON)
├── specs/                    # Epic specs (Markdown)
│   └── fn-N-xxx.md
├── tasks/                    # Task specs (Markdown)
│   └── fn-N-xxx.M.md
├── config.json               # Project configuration
├── meta.json                 # Flow metadata
│
├── review_state.json         # NEW: Fingerprints, blockers
├── quota_state.json          # NEW: Multi-source quota tracking
├── metrics.json              # NEW: Telemetry
│
├── memory/                   # Existing memory system
│   ├── pitfalls.md
│   ├── conventions.md
│   └── decisions.md
│
└── cache/                    # NEW: Scout result caching
    ├── repo-scout/
    ├── practice-scout/
    └── docs-scout/

---

3. Resource Inventory

3.1 Premium Sources

Source	Subscription	Models	Best For	Access
OpenAI Pro	$200/mo	Codex 5.2, GPT-4o	Security review	API
Claude Max	$200/mo	Opus 4.5, Sonnet 4	Complex reasoning	API, Claude Code
Copilot Pro+	$39/mo	Opus 4.5, Codex 5.2, Sonnet 4	Flexible routing	Coding Agent
Antigravity	~$25/mo	Opus 4.5, Gemini 3 Pro	Additional capacity	CLI

3.2 Local Hardware

Component	Specification	Role
GPU	NVIDIA RTX 5090 32GB VRAM	Model inference
RAM	128GB DDR5	Extended context
Storage	Gen5 NVMe 14.9 GB/s	Fast model loading

3.3 Local Models

GLM-4.7-Flash (Primary)

Attribute	Value
Model	GLM-4.7-Flash-UD-Q4_K_XL
SWE-Bench	59.2% (best local)
Parameters	30B total, ~3.6B active (MoE)
Context	Up to 200K tokens
VRAM	23-30GB (context dependent)
Speed	60-100 tok/s

VRAM by Context:

Context	VRAM	7B Colocate?
32K	~20 GB	✅ Yes
65K	~23 GB	✅ Yes
131K	~30 GB	❌ No

Qwen2.5-Coder-7B (Pre-filter)

Attribute	Value
Model	qwen2.5-coder:7b-instruct-q8_0
Context	32K tokens
VRAM	~8 GB
Speed	100-120 tok/s
Role	Fast pre-filter

---

4. Phase 1: Interview

4.1 Overview

Interview is human-paced and low token burn by nature. Optimization focuses on question quality and spec drafting assistance.

┌─────────────────────────────────────────────────────────────────────────────┐
│                         INTERVIEW OPTIMIZATION                               │
└─────────────────────────────────────────────────────────────────────────────┘

Current: All questions generated by premium model
Optimized: Local generates question candidates, premium refines

Token Savings: 30-50% (interview is already low burn)
Quality Impact: None (human validates all questions)

4.2 Optimization Strategy

4.2.1 Local Question Generation

GLM-4.7-Flash generates initial question batches based on input:

def generate_interview_questions(
    input_type: str,  # epic, task, file, idea
    content: str,
    category: str,  # scope, technical, edge_cases, etc.
) -> list[str]:
    """Generate interview questions locally."""
    
    prompt = f"""Generate interview questions for a {input_type}.

## Content
{content}

## Category: {category}

## Question Guidelines
- Dig deep on hidden complexity
- Surface assumptions
- Identify edge cases
- Group related questions (2-4 per batch)

Generate 5-10 questions for this category.
"""
    
    return run_glm47_flash(prompt)

4.2.2 Premium Refinement

Premium model reviews and refines questions only when:

• Questions seem superficial
• Domain requires specialized knowledge
• User requests deeper exploration

4.3 Interview Flow (Optimized)

┌─────────────────────────────────────────────────────────────────────────────┐
│                         INTERVIEW FLOW                                       │
└─────────────────────────────────────────────────────────────────────────────┘

Input (epic/task/file/idea)
          │
          ▼
┌─────────────────┐
│ GLM-4.7-Flash   │  ← LOCAL: Parse input, identify question categories
│ Question Gen    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Human Q&A Loop  │  ← Questions via AskUserQuestion tool
│ (40+ questions) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ GLM-4.7-Flash   │  ← LOCAL: Draft refined spec from answers
│ Spec Drafting   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Human Review    │  ← User approves/edits
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Write to        │  ← flowctl epic set-plan / task set-spec
│ .flow/specs/    │
└─────────────────┘

4.4 Configuration

{
  "interview": {
    "question_generation": {
      "backend": "local",
      "model": "GLM-4.7-Flash",
      "fallback_to_premium": true
    },
    "spec_drafting": {
      "backend": "local",
      "model": "GLM-4.7-Flash"
    },
    "premium_refinement": {
      "enabled": true,
      "trigger": "user_request_or_shallow_questions"
    }
  }
}

---

5. Phase 2: Plan

5.1 Overview

Planning involves parallel scout agents that analyze the codebase. Current implementation runs all scouts via premium models. Optimization runs scouts locally with premium for final spec writing.

┌─────────────────────────────────────────────────────────────────────────────┐
│                           PLAN OPTIMIZATION                                  │
└─────────────────────────────────────────────────────────────────────────────┘

Current Scout Agents (all premium):
├── repo-scout      - Codebase analysis
├── practice-scout  - Best practices research
├── docs-scout      - Documentation analysis
├── github-scout    - GitHub issues/PRs
├── epic-scout      - Epic dependencies
└── docs-gap-scout  - Documentation gaps

Optimized:
├── repo-scout      - LOCAL (GLM-4.7-Flash)
├── practice-scout  - LOCAL (GLM-4.7-Flash)
├── docs-scout      - LOCAL (GLM-4.7-Flash)
├── github-scout    - PREMIUM (needs API access)
├── epic-scout      - LOCAL (GLM-4.7-Flash)
└── docs-gap-scout  - LOCAL (GLM-4.7-Flash)

Token Savings: 60-70% of planning phase
Quality Impact: Minimal (scouts gather info, premium synthesizes)

5.2 Scout Agent Optimization

5.2.1 Local Scout Execution

class LocalScoutRunner:
    """Run scout agents locally via GLM-4.7-Flash."""
    
    def __init__(self, glm_backend: LlamaCppBackend):
        self.glm = glm_backend
        self.cache_dir = Path(".flow/cache")
    
    def run_repo_scout(self, feature_description: str) -> ScoutResult:
        """Analyze codebase for relevant patterns."""
        
        # Check cache first
        cache_key = self._cache_key("repo", feature_description)
        if cached := self._get_cache(cache_key):
            return cached
        
        # Gather codebase info
        file_tree = self._get_file_tree()
        recent_commits = self._get_recent_commits(30)
        
        prompt = f"""Analyze this codebase for implementing: {feature_description}

## File Structure
{file_tree}

## Recent Commits
{recent_commits}

## Tasks
1. Identify files likely to be modified
2. Find similar patterns in the codebase
3. Note relevant imports/dependencies
4. Flag potential conflicts

Output structured findings.
"""
        
        result = self.glm.generate(prompt)
        self._set_cache(cache_key, result)
        return result
    
    def run_practice_scout(self, feature_description: str) -> ScoutResult:
        """Research best practices for the feature."""
        
        prompt = f"""Research best practices for: {feature_description}

Consider:
1. Common implementation patterns
2. Security considerations
3. Performance implications
4. Testing strategies
5. Error handling approaches

Base recommendations on industry standards and common patterns.
"""
        
        return self.glm.generate(prompt)
    
    def run_epic_scout(self, new_epic_id: str) -> ScoutResult:
        """Find dependencies on existing epics."""
        
        # Read all existing epics
        epics = self._load_all_epics()
        
        prompt = f"""Analyze dependencies for new epic {new_epic_id}.

## Existing Epics
{self._format_epics(epics)}

## New Epic
{self._load_epic(new_epic_id)}

Identify:
1. Which existing epics this depends on
2. Specific tasks/components used
3. Potential conflicts
"""
        
        return self.glm.generate(prompt)

5.2.2 Scout Result Caching

class ScoutCache:
    """Cache scout results to avoid redundant analysis."""
    
    def __init__(self, cache_dir: Path):
        self.cache_dir = cache_dir
        self.ttl_hours = 24  # Results valid for 24 hours
    
    def get(self, scout_type: str, key: str) -> Optional[ScoutResult]:
        cache_file = self.cache_dir / scout_type / f"{self._hash(key)}.json"
        
        if not cache_file.exists():
            return None
        
        data = json.loads(cache_file.read_text())
        
        # Check TTL
        cached_at = datetime.fromisoformat(data["cached_at"])
        if datetime.now() - cached_at > timedelta(hours=self.ttl_hours):
            return None
        
        # Check if codebase changed significantly
        if data.get("git_hash") != self._current_git_hash():
            # Invalidate if significant changes
            changed_files = self._get_changed_files(data["git_hash"])
            if self._significant_changes(changed_files, data.get("relevant_files", [])):
                return None
        
        return ScoutResult.from_dict(data["result"])
    
    def set(self, scout_type: str, key: str, result: ScoutResult):
        cache_file = self.cache_dir / scout_type / f"{self._hash(key)}.json"
        cache_file.parent.mkdir(parents=True, exist_ok=True)
        
        data = {
            "cached_at": datetime.now().isoformat(),
            "git_hash": self._current_git_hash(),
            "relevant_files": result.relevant_files,
            "result": result.to_dict(),
        }
        
        cache_file.write_text(json.dumps(data, indent=2))

5.3 Planning Flow (Optimized)

┌─────────────────────────────────────────────────────────────────────────────┐
│                           PLANNING FLOW                                      │
└─────────────────────────────────────────────────────────────────────────────┘

Input (feature idea or epic ID)
          │
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PARALLEL SCOUT EXECUTION                                                    │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ repo-scout  │  │ practice-   │  │ docs-scout  │  │ epic-scout  │       │
│  │   LOCAL     │  │ scout LOCAL │  │   LOCAL     │  │   LOCAL     │       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘       │
│         │                │                │                │               │
│         └────────────────┴────────────────┴────────────────┘               │
│                                    │                                        │
│                                    ▼                                        │
│                          ┌─────────────────┐                               │
│                          │ Scout Results   │                               │
│                          │ Aggregation     │                               │
│                          └────────┬────────┘                               │
└───────────────────────────────────┼─────────────────────────────────────────┘
                                    │
                                    ▼
                          ┌─────────────────┐
                          │ GLM-4.7-Flash   │  ← LOCAL: Draft epic spec
                          │ Spec Drafting   │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ PREMIUM         │  ← Opus 4.5: Architectural review
                          │ Spec Review     │     (optional, on request)
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ Task Breakdown  │  ← LOCAL: Create task specs
                          │ GLM-4.7-Flash   │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ Write to .flow/ │
                          └─────────────────┘

5.4 Plan Review Optimization

Plan reviews follow the same optimization as impl reviews:

def review_plan(epic_id: str) -> ReviewResult:
    """Review epic plan with optimized pipeline."""
    
    # 1. Local pre-screen
    prescreen = local_prescreen_plan(epic_id)
    if prescreen.verdict == "NEEDS_WORK":
        return prescreen  # Fix locally
    
    # 2. Classify complexity
    complexity = classify_plan_complexity(epic_id)
    
    # 3. Route to appropriate premium
    if complexity == "SIMPLE":
        # Sonnet 4 or Gemini 3 Pro
        return route_to_cheapest_premium(epic_id, "plan")
    else:
        # Opus 4.5 for complex architectural review
        return route_to_opus(epic_id, "plan")

5.5 Configuration

{
  "plan": {
    "scouts": {
      "repo_scout": {"backend": "local", "cache_ttl_hours": 24},
      "practice_scout": {"backend": "local", "cache_ttl_hours": 168},
      "docs_scout": {"backend": "local", "cache_ttl_hours": 24},
      "github_scout": {"backend": "premium", "model": "sonnet-4"},
      "epic_scout": {"backend": "local", "cache_ttl_hours": 24},
      "docs_gap_scout": {"backend": "local", "cache_ttl_hours": 24}
    },
    "spec_drafting": {
      "backend": "local",
      "model": "GLM-4.7-Flash"
    },
    "task_breakdown": {
      "backend": "local",
      "model": "GLM-4.7-Flash"
    },
    "plan_review": {
      "simple": {"backend": "sonnet-4"},
      "complex": {"backend": "opus-4.5"}
    }
  }
}

---

6. Phase 3: Work

6.1 Overview

Work phase is the highest token consumer due to implementation complexity. Current worker agents get full context from premium models. Optimization uses local models for re-anchoring and routine implementation while premium handles complex decisions.

┌─────────────────────────────────────────────────────────────────────────────┐
│                           WORK OPTIMIZATION                                  │
└─────────────────────────────────────────────────────────────────────────────┘

Current Worker Flow:
  Premium spawns worker → Premium implements → Premium reviews

Optimized Worker Flow:
  Local re-anchor → Local/Premium implements (based on complexity) → Local pre-screen → Premium reviews

Token Savings: 40-60% of work phase
Quality Impact: Minimal (premium for complex decisions)

6.2 Worker Agent Optimization

6.2.1 Complexity-Based Model Selection

class WorkerModelSelector:
    """Select model for worker based on task complexity."""
    
    def select_model(self, task_id: str) -> ModelConfig:
        task = load_task(task_id)
        epic = load_epic(task.epic_id)
        
        # Analyze task complexity
        complexity = self.analyze_complexity(task, epic)
        
        if complexity.level == "LOW":
            # Simple tasks: Local GLM-4.7-Flash
            return ModelConfig(
                backend="local",
                model="GLM-4.7-Flash",
                reason="Simple task, local model sufficient"
            )
        
        elif complexity.level == "MEDIUM":
            # Moderate tasks: Hybrid approach
            return ModelConfig(
                backend="hybrid",
                local_model="GLM-4.7-Flash",
                premium_model="sonnet-4",
                strategy="local_first_premium_fallback",
                reason="Moderate complexity, try local first"
            )
        
        else:  # HIGH
            # Complex tasks: Premium model
            return ModelConfig(
                backend="premium",
                model=self.select_premium_model(complexity),
                reason="Complex task requires premium reasoning"
            )
    
    def analyze_complexity(self, task: Task, epic: Epic) -> TaskComplexity:
        """Analyze task complexity for model selection."""
        
        indicators = {
            "security_sensitive": self.is_security_sensitive(task),
            "architectural": self.is_architectural(task),
            "concurrency": self.involves_concurrency(task),
            "unfamiliar_patterns": self.uses_unfamiliar_patterns(task),
            "large_scope": task.size in ["L", "XL"],
            "many_files": len(task.estimated_files) > 5,
            "cross_module": self.is_cross_module(task),
        }
        
        high_indicators = sum(indicators.values())
        
        if high_indicators >= 3 or indicators["security_sensitive"]:
            return TaskComplexity(level="HIGH", indicators=indicators)
        elif high_indicators >= 1:
            return TaskComplexity(level="MEDIUM", indicators=indicators)
        else:
            return TaskComplexity(level="LOW", indicators=indicators)

6.2.2 Local Re-Anchor Summaries

Workers re-anchor before implementation. Instead of full premium processing, local model creates summaries:

def local_reanchor(task_id: str, epic_id: str) -> ReanchorContext:
    """Create re-anchor context using local model."""
    
    # Read specs
    task_spec = flowctl_cat(task_id)
    epic_spec = flowctl_cat(epic_id)
    
    # Read memory
    memory = read_memory_files()
    
    # Check git state
    git_status = run("git status")
    git_log = run("git log -5 --oneline")
    
    # Local model creates focused summary
    prompt = f"""Create implementation context summary for task {task_id}.

## Task Spec
{task_spec}

## Epic Context
{epic_spec}

## Memory (pitfalls, conventions)
{memory}

## Git State
{git_status}
{git_log}

Create a focused summary:
1. Key acceptance criteria (bullet points)
2. Files likely to modify
3. Relevant patterns from memory
4. Dependencies to be aware of
5. Test requirements
"""
    
    summary = run_glm47_flash(prompt)
    
    return ReanchorContext(
        task_id=task_id,
        summary=summary,
        task_spec=task_spec,  # Full spec still available
        epic_spec=epic_spec,
    )

6.2.3 Hybrid Implementation Strategy

class HybridWorker:
    """Worker that uses local for routine code, premium for complex decisions."""
    
    def implement(self, task_id: str, context: ReanchorContext) -> ImplementResult:
        model_config = self.model_selector.select_model(task_id)
        
        if model_config.backend == "local":
            return self.implement_local(task_id, context)
        
        elif model_config.backend == "hybrid":
            # Try local first
            result = self.implement_local(task_id, context)
            
            if result.confidence < 0.8 or result.needs_premium_decision:
                # Escalate to premium for specific decisions
                return self.escalate_to_premium(task_id, context, result)
            
            return result
        
        else:  # premium
            return self.implement_premium(task_id, context, model_config)
    
    def implement_local(self, task_id: str, context: ReanchorContext) -> ImplementResult:
        """Implement using GLM-4.7-Flash."""
        
        prompt = f"""Implement task {task_id}.

## Context
{context.summary}

## Full Task Spec (reference)
{context.task_spec}

## Instructions
1. Read relevant code files
2. Implement changes following existing patterns
3. Add tests if spec requires
4. Keep changes focused and minimal

If you encounter:
- Security-sensitive decisions → Flag for premium review
- Unfamiliar patterns → Flag for premium assistance
- Architectural choices → Flag for premium decision

Output your implementation plan, then implement.
"""
        
        return self.glm.implement(prompt)

6.3 Work Flow (Optimized)

┌─────────────────────────────────────────────────────────────────────────────┐
│                            WORK FLOW                                         │
└─────────────────────────────────────────────────────────────────────────────┘

                        /flow-next:work fn-1
                               │
                               ▼
                    ┌─────────────────┐
                    │ Setup Questions │
                    │ (branch, review)│
                    └────────┬────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ TASK LOOP                                                                   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ flowctl ready --epic fn-1 → next task                               │   │
│  └──────────────────────────────────┬──────────────────────────────────┘   │
│                                     │                                       │
│                                     ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ SPAWN WORKER (subagent)                                             │   │
│  │                                                                     │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ LOCAL RE-ANCHOR │ ← GLM-4.7-Flash creates focused summary       │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │           ▼                                                         │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ CLASSIFY TASK   │ ← Determine LOCAL / HYBRID / PREMIUM          │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │     ┌─────┴─────┐                                                   │   │
│  │     ▼           ▼                                                   │   │
│  │  ┌──────┐  ┌──────────┐                                             │   │
│  │  │LOCAL │  │PREMIUM   │                                             │   │
│  │  │impl  │  │impl      │                                             │   │
│  │  └──┬───┘  └────┬─────┘                                             │   │
│  │     │           │                                                   │   │
│  │     └─────┬─────┘                                                   │   │
│  │           │                                                         │   │
│  │           ▼                                                         │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ COMMIT          │                                                │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │           ▼                                                         │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ REVIEW          │ ← See Phase 4                                  │   │
│  │  │ (if enabled)    │                                                │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │           ▼                                                         │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ COMPLETE        │ ← flowctl done                                 │   │
│  │  └─────────────────┘                                                │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                     │                                       │
│                                     ▼                                       │
│                          Next task or Quality phase                         │
└──────────────────────────────────��──────────────────────────────────────────┘

6.4 Configuration

{
  "work": {
    "model_selection": {
      "strategy": "complexity_based",
      "low_complexity": {
        "backend": "local",
        "model": "GLM-4.7-Flash"
      },
      "medium_complexity": {
        "backend": "hybrid",
        "local_model": "GLM-4.7-Flash",
        "premium_model": "sonnet-4",
        "strategy": "local_first_premium_fallback"
      },
      "high_complexity": {
        "backend": "premium",
        "security": "codex-5.2",
        "architectural": "opus-4.5",
        "default": "opus-4.5"
      }
    },
    "reanchor": {
      "backend": "local",
      "model": "GLM-4.7-Flash",
      "include_memory": true
    },
    "worker": {
      "subagent": true,
      "fresh_context": true
    }
  }
}

---

7. Phase 4: Review

7.1 Overview

Review phase has the highest token burn due to:

1. Full context sent to premium models
2. Multiple review iterations per task
3. Re-reviewing unchanged code
4. Verbose prompts

This is the primary optimization target.

7.2 Review Pipeline

┌─────────────────────────────────────────────────────────────────────────────┐
│                         REVIEW PIPELINE                                      │
└─────────────────────────────────────────────────────────────────────────────┘

                              Review Request
                                    │
                                    ▼
                         ┌─────────────────┐
                         │ STAGE 1: GATES  │  ← FREE (deterministic)
                         │ lint/build/tsc  │
                         └────────┬────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │ STAGE 2:        │  ← FREE (GLM-4.7-Flash)
                         │ PRE-SCREEN      │
                         │                 │
                         │ Find obvious    │
                         │ issues, fix     │
                         │ locally         │
                         └────────┬────────┘
                                  │
                                  ▼
                         ┌───────��─────────┐
                         │ STAGE 3:        │  ← FREE (SHA-256)
                         │ FINGERPRINT     │
                         │                 │
                         │ Skip if diff    │
                         │ unchanged       │
                         └────────┬────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │ STAGE 4:        │  ← FREE (GLM-4.7-Flash)
                         │ CLASSIFY        │
                         │                 │
                         │ SECURITY /      │
                         │ COMPLEX /       │
                         │ ROUTINE         │
                         └────────┬────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │ STAGE 5:        │  ← Multi-source pooling
                         │ ROUTE           │
                         │                 │
                         │ Select best     │
                         │ available src   │
                         └────────┬────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          ▼                       ▼                       ▼
    ┌───────────┐          ┌───────────┐          ┌───────────┐
    │ SECURITY  │          │ COMPLEX   │          │ ROUTINE   │
    │           │          │           │          │           │
    │ Codex 5.2 │          │ Opus 4.5  │          │ Sonnet 4  │
    │ preferred │          │ preferred │          │ or lowest │
    └─────┬─────┘          └─────┬─────┘          └─────┬─────┘
          │                      │                      │
          └──────────────────────┴──────────────────────┘
                                 │
                                 ▼
                         ┌─────────────────┐
                         │ STAGE 6:        │
                         │ PREMIUM REVIEW  │
                         │                 │
                         │ Full context    │
                         │ Lean prompt     │
                         │ Final verdict   │
                         └────────┬────────┘
                                  │
                                  ▼
                           SHIP / NEEDS_WORK

7.3 Stage Details

See the detailed specifications in Section 6 of the earlier review-focused spec. Key points:

7.3.1 Stage 2: Pre-Screen

GLM-4.7-Flash catches obvious issues:

• Missing imports
• Undefined variables
• Obvious null access
• Logic errors
• Missing returns

Expected catch rate: 40-60% of NEEDS_WORK issues

7.3.2 Stage 3: Fingerprint

Prevent re-reviewing unchanged code:

fingerprint = sha256(normalize(git diff base..HEAD))

# Skip if:
# - Same fingerprint as last NEEDS_WORK
# - Blocker files not touched

Expected skip rate: 20-40% of reviews

7.3.3 Stage 4: Classification

Route to appropriate premium model:

Type	Patterns	Model
SECURITY	auth, crypto, password, token	Codex 5.2
COMPLEX	core, architecture, concurrent	Opus 4.5
ROUTINE	tests, docs, simple fixes	Sonnet 4

7.3.4 Stage 5: Quota-Aware Routing

Select from 4 premium sources based on availability:

Source	Models	Status Tracking
OpenAI Pro	Codex 5.2, GPT-4o	.flow/quota_state.json
Claude Max	Opus 4.5, Sonnet 4	.flow/quota_state.json
Copilot	Opus, Codex, Sonnet	.flow/quota_state.json
Antigravity	Opus, Gemini 3 Pro	.flow/quota_state.json

7.3.5 Stage 6: Premium Review

CRITICAL: No lossy compression. Premium sees full context:

• Changed files (full content)
• Direct imports (full content)
• Test files (full content)
• Diff (full)

Savings come from:

• Pre-screening (fewer reviews)
• Fingerprinting (skip unchanged)
• Lean prompts (~500 tokens vs 3000)
• Multi-source pooling (capacity)

7.4 Configuration

{
  "review": {
    "gates": {
      "enabled": true,
      "checks": ["lint", "build", "typecheck"]
    },
    "prescreen": {
      "enabled": true,
      "backend": "local",
      "model": "GLM-4.7-Flash",
      "max_iterations": 3
    },
    "fingerprint": {
      "enabled": true,
      "skip_unchanged": true,
      "require_blocker_change": true
    },
    "classification": {
      "security_patterns": ["**/auth/**", "**/crypto/**", "**/*password*"],
      "complex_patterns": ["**/core/**", "**/architect*"]
    },
    "routing": {
      "security": ["openai_pro:codex-5.2", "copilot:codex-5.2"],
      "complex": ["claude_max:opus-4.5", "copilot:opus-4.5"],
      "routine": ["quota_lowest", "copilot:sonnet-4"]
    },
    "premium_sources": {
      "openai_pro": {"enabled": true, "api_key_env": "OPENAI_API_KEY"},
      "claude_max": {"enabled": true, "api_key_env": "ANTHROPIC_API_KEY"},
      "copilot": {"enabled": true, "access_method": "coding_agent"},
      "antigravity": {"enabled": true, "access_method": "cli"}
    }
  }
}

---

8. Local Model Infrastructure

8.1 Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      LOCAL MODEL INFRASTRUCTURE                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ llama-swap (Port 8080)                                                      │
│                                                                             │
│ Proxy that manages model loading/unloading for llama.cpp                    │
│ - Routes requests to appropriate model                                       │
│ - Frees GPU memory when idle                                                │
│ - Enables model hot-swapping                                                │
│                                                                             │
│ Endpoints:                                                                   │
│   /v1/chat/completions  → Anthropic/OpenAI compatible                       │
│   /completion           → llama.cpp native                                  │
│   /health               → Health check                                      │
│   /swap                 → Model swap control                                │
└─────────────────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│ llama-server            │     │ Ollama (Port 11434)     │
│ GLM-4.7-Flash           │     │ Qwen2.5-Coder-7B        │
│                         │     │                         │
│ Context: 65K default    │     │ Always hot (keep_alive) │
│ VRAM: ~23GB             │     │ VRAM: ~8GB              │
│ Speed: 60-100 tok/s     │     │ Speed: 100+ tok/s       │
└─────────────────────────┘     └─────────────────────────┘

8.2 llama-swap Configuration

Based on the tammam.io guide, llama-swap enables:

• Model hot-swapping without restart
• Memory management (free GPU when idle)
• Anthropic API compatibility (for Claude Code integration)

# llama-swap.yaml
listen: 0.0.0.0:8080

models:
  glm-4.7-flash:
    cmd: >
      llama-server
      -m /models/GLM-4.7-Flash-UD-Q4_K_XL.gguf
      -ngl 99
      -c 65536
      --cache-type-k q4_0
      --cache-type-v q4_0
      -fa
      --mmap
      -t 8
    ttl: 300  # Unload after 5 min idle
    
  glm-4.7-flash-large:
    cmd: >
      llama-server
      -m /models/GLM-4.7-Flash-UD-Q4_K_XL.gguf
      -ngl 99
      -c 131072
      --cache-type-k q4_0
      --cache-type-v q4_0
      -fa
      --mmap
      -t 8
    ttl: 300

aliases:
  claude-3-5-sonnet-20241022: glm-4.7-flash  # Claude Code compatibility
  gpt-4: glm-4.7-flash  # OpenAI compatibility

healthcheck:
  interval: 30
  timeout: 5

8.3 Startup Script

#!/bin/bash
# start-local-stack.sh

set -e

MODELS_DIR="${MODELS_DIR:-$HOME/models}"
LLAMA_SWAP_CONFIG="${LLAMA_SWAP_CONFIG:-./llama-swap.yaml}"

echo "=== Starting Local Model Stack ==="

# 1. Start Ollama for 7B pre-filter
echo "[1/3] Starting Ollama..."
if ! pgrep -x "ollama" > /dev/null; then
    ollama serve &
    sleep 2
fi

# Pull and warm up 7B model
ollama pull qwen2.5-coder:7b-instruct-q8_0 2>/dev/null || true
curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen2.5-coder:7b-instruct-q8_0",
  "prompt": "ready",
  "keep_alive": "24h"
}' > /dev/null

echo "  ✓ Ollama ready (7B pre-filter, ~8GB VRAM)"

# 2. Start llama-swap
echo "[2/3] Starting llama-swap..."
if ! pgrep -x "llama-swap" > /dev/null; then
    llama-swap -c "$LLAMA_SWAP_CONFIG" &
    sleep 2
fi

# Wait for llama-swap
until curl -s http://localhost:8080/health > /dev/null 2>&1; do
    sleep 1
done

echo "  ✓ llama-swap ready (port 8080)"

# 3. Pre-warm GLM-4.7-Flash
echo "[3/3] Pre-warming GLM-4.7-Flash..."
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "glm-4.7-flash", "messages": [{"role": "user", "content": "ready"}], "max_tokens": 1}' \
  > /dev/null

echo "  ✓ GLM-4.7-Flash ready (~23GB VRAM)"

echo ""
echo "=== Local Stack Ready ==="
echo "  Pre-filter (7B):   http://localhost:11434"
echo "  GLM-4.7-Flash:     http://localhost:8080"
echo ""
echo "VRAM Usage: ~31GB (7B: 8GB + GLM: 23GB)"

8.4 Integration with Claude Code

Using the Anthropic-compatible endpoint from llama-swap:

# Set environment for Claude Code to use local model
export ANTHROPIC_BASE_URL=http://localhost:8080/v1
export ANTHROPIC_API_KEY=local  # Dummy key for llama-swap

# Now Claude Code uses local GLM-4.7-Flash
claude "Review this code..."

8.5 Integration with Codex CLI

# Codex can also use the OpenAI-compatible endpoint
export OPENAI_BASE_URL=http://localhost:8080/v1
export OPENAI_API_KEY=local

# For specific commands, use local
codex --api-base http://localhost:8080/v1 "..."

---

9. Multi-Source Orchestration

9.1 Quota Tracking

class QuotaTracker:
    """Track quota usage across all premium sources."""
    
    def __init__(self, state_file: Path = Path(".flow/quota_state.json")):
        self.state_file = state_file
        self.load()
    
    def get_status(self, source: str) -> QuotaStatus:
        """Get current quota status for a source."""
        state = self.state.get("sources", {}).get(source, {})
        
        return QuotaStatus(
            source=source,
            remaining_pct=state.get("remaining_pct", 1.0),
            is_throttled=state.get("is_throttled", False),
            last_request=datetime.fromisoformat(state.get("last_request", "1970-01-01")),
            requests_since_reset=state.get("requests_since_reset", 0),
        )
    
    def record_usage(self, source: str, tokens: int, was_throttled: bool = False):
        """Record usage for quota tracking."""
        if "sources" not in self.state:
            self.state["sources"] = {}
        
        if source not in self.state["sources"]:
            self.state["sources"][source] = {
                "remaining_pct": 1.0,
                "requests_since_reset": 0,
                "tokens_since_reset": 0,
            }
        
        s = self.state["sources"][source]
        s["last_request"] = datetime.now().isoformat()
        s["requests_since_reset"] = s.get("requests_since_reset", 0) + 1
        s["tokens_since_reset"] = s.get("tokens_since_reset", 0) + tokens
        s["is_throttled"] = was_throttled
        
        # Estimate remaining (heuristic based on usage patterns)
        s["remaining_pct"] = self._estimate_remaining(source, s)
        
        self.save()
    
    def get_best_for_task_type(self, task_type: str) -> list[tuple[str, str]]:
        """Get best available sources for task type, sorted by preference."""
        routing = self._get_routing_config()
        candidates = routing.get(task_type, [])
        
        available = []
        for candidate in candidates:
            if candidate == "quota_lowest":
                # Special: select source with most remaining quota
                best = self._get_highest_remaining()
                if best:
                    available.append(best)
            else:
                source, model = candidate.split(":")
                status = self.get_status(source)
                if not status.is_throttled and status.remaining_pct > 0.05:
                    available.append((source, model))
        
        return available

9.2 Backend Implementations

9.2.1 OpenAI Backend

class OpenAIBackend(PremiumBackend):
    """OpenAI Pro backend (Codex 5.2, GPT-4o)."""
    
    source_name = "openai_pro"
    
    def __init__(self):
        self.api_key = os.environ.get("OPENAI_API_KEY")
        self.client = OpenAI(api_key=self.api_key)
    
    def review(self, context: ReviewContext, task_type: str) -> ReviewResult:
        model = "gpt-5.2" if task_type == "security" else "gpt-4o"
        
        response = self.client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": context.prompt}],
            temperature=0.1,
            max_tokens=2048,
        )
        
        return ReviewResult(
            source=self.source_name,
            model=model,
            content=response.choices[0].message.content,
            tokens_input=response.usage.prompt_tokens,
            tokens_output=response.usage.completion_tokens,
        )

9.2.2 Claude Backend

class ClaudeBackend(PremiumBackend):
    """Claude Max backend (Opus 4.5, Sonnet 4)."""
    
    source_name = "claude_max"
    
    def __init__(self):
        self.api_key = os.environ.get("ANTHROPIC_API_KEY")
        self.client = Anthropic(api_key=self.api_key)
    
    def review(self, context: ReviewContext, task_type: str) -> ReviewResult:
        model = "claude-opus-4-5-20250514" if task_type in ["security", "complex"] else "claude-sonnet-4-20250514"
        
        response = self.client.messages.create(
            model=model,
            max_tokens=2048,
            messages=[{"role": "user", "content": context.prompt}],
        )
        
        return ReviewResult(
            source=self.source_name,
            model=model,
            content=response.content[0].text,
            tokens_input=response.usage.input_tokens,
            tokens_output=response.usage.output_tokens,
        )

9.2.3 Copilot Backend

class CopilotBackend(PremiumBackend):
    """GitHub Copilot Pro+ backend."""
    
    source_name = "copilot"
    
    def review(self, context: ReviewContext, task_type: str) -> ReviewResult:
        # Copilot accessed via coding agent
        model = self._select_model(task_type)
        
        # Use GitHub Copilot Coding Agent API
        result = self._invoke_coding_agent(context, model)
        
        return ReviewResult(
            source=self.source_name,
            model=model,
            content=result.content,
            tokens_input=result.tokens_input,
            tokens_output=result.tokens_output,
        )
    
    def _select_model(self, task_type: str) -> str:
        if task_type == "security":
            return "codex-5.2"
        elif task_type == "complex":
            return "claude-opus-4-5"
        else:
            return "claude-sonnet-4"

9.2.4 Antigravity Backend

class AntigravityBackend(PremiumBackend):
    """Google Antigravity backend (Opus 4.5, Gemini 3 Pro)."""
    
    source_name = "antigravity"
    
    def review(self, context: ReviewContext, task_type: str) -> ReviewResult:
        model = "claude-opus-4-5" if task_type in ["security", "complex"] else "gemini-3-pro"
        
        # Use Antigravity CLI
        result = self._invoke_antigravity(context, model)
        
        return ReviewResult(
            source=self.source_name,
            model=model,
            content=result.content,
            tokens_input=result.tokens_input,
            tokens_output=result.tokens_output,
        )

---

10. Configuration Reference

10.1 Complete .flow/config.json

{
  "schema_version": 2,
  
  "interview": {
    "question_generation": {
      "backend": "local",
      "model": "GLM-4.7-Flash"
    },
    "spec_drafting": {
      "backend": "local"
    }
  },
  
  "plan": {
    "scouts": {
      "repo_scout": {"backend": "local", "cache_ttl_hours": 24},
      "practice_scout": {"backend": "local", "cache_ttl_hours": 168},
      "docs_scout": {"backend": "local", "cache_ttl_hours": 24},
      "github_scout": {"backend": "premium", "model": "sonnet-4"},
      "epic_scout": {"backend": "local"},
      "docs_gap_scout": {"backend": "local"}
    },
    "spec_drafting": {"backend": "local"},
    "task_breakdown": {"backend": "local"}
  },
  
  "work": {
    "model_selection": {
      "strategy": "complexity_based",
      "low_complexity": {"backend": "local"},
      "medium_complexity": {"backend": "hybrid"},
      "high_complexity": {"backend": "premium"}
    },
    "reanchor": {"backend": "local"}
  },
  
  "review": {
    "gates": {
      "enabled": true,
      "checks": ["lint", "build", "typecheck"]
    },
    "prescreen": {
      "enabled": true,
      "backend": "local",
      "max_iterations": 3
    },
    "fingerprint": {
      "enabled": true,
      "skip_unchanged": true,
      "require_blocker_change": true
    },
    "classification": {
      "security_patterns": [
        "**/auth/**", "**/crypto/**", "**/security/**",
        "**/*password*", "**/*secret*", "**/*token*"
      ],
      "complex_patterns": [
        "**/core/**", "**/architect*", "**/concurrent*"
      ]
    },
    "routing": {
      "security": ["openai_pro:codex-5.2", "copilot:codex-5.2"],
      "complex": ["claude_max:opus-4.5", "copilot:opus-4.5", "antigravity:opus-4.5"],
      "routine": ["quota_lowest", "copilot:sonnet-4", "antigravity:gemini-3-pro"]
    }
  },
  
  "premium_sources": {
    "openai_pro": {
      "enabled": true,
      "api_key_env": "OPENAI_API_KEY",
      "models": ["gpt-5.2", "codex-5.2", "gpt-4o"]
    },
    "claude_max": {
      "enabled": true,
      "api_key_env": "ANTHROPIC_API_KEY",
      "models": ["claude-opus-4-5-20250514", "claude-sonnet-4-20250514"]
    },
    "copilot": {
      "enabled": true,
      "access_method": "coding_agent",
      "models": ["claude-opus-4-5", "codex-5.2", "claude-sonnet-4"]
    },
    "antigravity": {
      "enabled": true,
      "access_method": "cli",
      "models": ["claude-opus-4-5", "gemini-3-pro"]
    }
  },
  
  "local": {
    "primary_model": "GLM-4.7-Flash-UD-Q4_K_XL",
    "primary_endpoint": "http://localhost:8080",
    "context_default": 65536,
    "context_max": 131072,
    "prefilter_model": "qwen2.5-coder:7b-instruct-q8_0",
    "prefilter_endpoint": "http://localhost:11434"
  },
  
  "memory": {
    "enabled": true
  }
}

10.2 Environment Variables (config.env for Ralph)

# === FLOW-NEXT TOKEN-OPTIMIZED CONFIGURATION ===

# --- LOCAL MODELS ---
LOCAL_ENABLED=1
LOCAL_ENDPOINT=http://localhost:8080
LOCAL_MODEL=GLM-4.7-Flash-UD-Q4_K_XL
LOCAL_CONTEXT_DEFAULT=65536

PREFILTER_ENABLED=1
PREFILTER_ENDPOINT=http://localhost:11434
PREFILTER_MODEL=qwen2.5-coder:7b-instruct-q8_0

# --- PREMIUM SOURCES ---
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

OPENAI_PRO_ENABLED=1
CLAUDE_MAX_ENABLED=1
COPILOT_ENABLED=1
ANTIGRAVITY_ENABLED=1

# --- REVIEW PIPELINE ---
GATES_ENABLED=1
PRESCREEN_ENABLED=1
PRESCREEN_MAX_ITERATIONS=3
FINGERPRINT_ENABLED=1
FINGERPRINT_SKIP_UNCHANGED=1

# --- WORK PIPELINE ---
WORK_

[clairernovotny]

Revised w/o Qwen2.5-Coder-7B as no clear benefit with some configs:

Flow-Next Token-Optimized Development System

Complete End-to-End Specification

---

Table of Contents

1. Executive Summary
2. Problem Statement
3. Goals and Non-Goals
4. Resource Inventory
5. System Architecture
6. Phase 1: Interview
7. Phase 2: Plan
8. Phase 3: Work
9. Phase 4: Review
10. Local Model Infrastructure
11. Multi-Source Premium Orchestration
12. State Management
13. CLI Reference
14. Configuration Reference
15. Implementation Roadmap
16. Appendices

---

1. Executive Summary

1.1 Overview

This specification defines a token-optimized development system for flow-next that maximizes code quality while dramatically reducing premium model token consumption. The system uses GLM-4.7-Flash (59.2% SWE-Bench) locally for preprocessing across all phases, while premium models (Opus 4.5, Codex 5.2, Gemini 3 Pro) make final decisions via multi-source quota pooling.

1.2 Key Principles

Principle	Description
Premium Always Judges	Premium models make 100% of final SHIP/NEEDS_WORK decisions
Local Handles Grunt Work	GLM-4.7-Flash handles pre-screening, scouts, classification, re-anchoring
Multi-Source Pooling	4 premium quota pools (OpenAI, Claude, Copilot, Antigravity)
No Lossy Compression	Full context for security/complex reviews
Simplicity	One local model (GLM-4.7-Flash), no complex model orchestration

1.3 Expected Outcomes

Metric	Current	Target	Method
Weekly quota duration	2 days	7+ days	Multi-source + local preprocessing
Premium calls per task	2-4	0.3-0.5	Local pre-screening
Review quality	100%	100%	Premium always decides
Pre-screen catch rate	0%	60-80%	GLM-4.7-Flash
Context window	32K	131K	Full VRAM to GLM-4.7-Flash

1.4 Model Stack

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MODEL STACK                                     │
└─────────────────────────────────────────────────────────────────────────────┘

LOCAL (FREE, UNLIMITED):
┌─────────────────────────���───────────────────────────────────────────────────┐
│ GLM-4.7-Flash Q4_K_XL                                                       │
│                                                                             │
│ • SWE-Bench: 59.2% (best local model available)                            │
│ • Architecture: 30B MoE, ~3.6B active                                       │
│ • Context: 131K tokens (full VRAM allocation)                               │
│ • Speed: 60-100 tok/s                                                       │
│ • VRAM: ~30GB                                                               │
│                                                                             │
│ Roles:                                                                       │
│ • Pre-screening (catch obvious issues before premium)                       │
│ • Scout agents (repo, practice, docs, epic analysis)                        │
│ • Task classification (SECURITY/COMPLEX/ROUTINE)                            │
│ • Re-anchoring (worker context summaries)                                   │
│ • Spec drafting (interview and plan phases)                                 │
└─────────────────────────────────────────────────────────────────────────────┘

PREMIUM (QUALITY, QUOTA-MANAGED):
┌─────────────────────────────────────────────────────────────────────────────┐
│ Multi-Source Pool                                                           │
│                                                                             │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│ │ OpenAI Pro  │ │ Claude Max  │ │ Copilot Pro+│ │ Antigravity │           │
│ │             │ │             │ │             │ │             │           │
│ │ Codex 5.2   │ │ Opus 4.5    │ │ Opus 4.5    │ │ Opus 4.5    │           │
│ │ GPT-4o      │ │ Sonnet 4    │ │ Codex 5.2   │ │ Gemini 3 Pro│           │
│ │             │ │             │ │ Sonnet 4    │ │             │           │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘           │
│                                                                             │
│ Routing:                                                                     │
│ • SECURITY tasks → Codex 5.2 (OpenAI or Copilot)                           │
│ • COMPLEX tasks → Opus 4.5 (Claude, Copilot, or Antigravity)               │
│ • ROUTINE tasks → Lowest quota source (Sonnet 4, Gemini 3 Pro)             │
└─────────────────────────────────────────────────────────────────────────────┘

---

2. Problem Statement

2.1 Current State

Flow-next's Ralph loops consume premium model tokens (Codex 5.2, Opus 4.5) across all phases, exhausting weekly quotas in approximately 2 days.

2.2 Token Burn Analysis

Phase	Token Burn	Primary Waste Sources
Interview	Low	Minimal (human-paced)
Plan	Medium	Scout agents all use premium
Work	High	Full context on every re-anchor
Review	Very High	Re-reviewing unchanged code, verbose prompts, multiple iterations

2.3 Root Causes

2.3.1 No Local Pre-Processing

Every operation goes directly to premium models:

Current Flow:
  Task complete → Premium review → NEEDS_WORK (missing semicolon)
  Fix semicolon → Premium review → NEEDS_WORK (typo)
  Fix typo → Premium review → NEEDS_WORK (null check)
  Fix null check → Premium review → SHIP

Premium calls: 4 (3 wasted on obvious issues)
Tokens burned: ~400K

2.3.2 No Fingerprint Deduplication

Unchanged diffs get re-reviewed, consuming identical tokens each time.

2.3.3 Single Premium Source

Current implementation uses one source until exhausted, leaving other quotas unused.

2.3.4 Verbose Prompts

Review prompts include ~3000 tokens of boilerplate criteria and examples.

2.4 Impact

Resource	Capacity	Current Burn Rate	Effective Availability
OpenAI Pro	Weekly quota	50%/day	2 days/week
Claude Max	High limit	20%/day	5 days/week
Copilot Pro+	Generous	~5%/day	Underutilized
Antigravity	Generous	~2%/day	Underutilized

---

3. Goals and Non-Goals

3.1 Goals

ID	Goal	Success Criteria
G1	Preserve review quality	Premium models make 100% of final decisions
G2	Extend quota lifespan	Weekly quotas last full week minimum
G3	Utilize all premium sources	Load distributed across all 4 sources
G4	Eliminate redundant reviews	Zero re-reviews of unchanged code
G5	Catch obvious issues locally	60%+ of NEEDS_WORK caught by GLM-4.7-Flash
G6	Maximize local context	131K token context window
G7	Simplify infrastructure	Single local model, no complex orchestration

3.2 Non-Goals

ID	Non-Goal	Rationale
NG1	Replace premium judgment with local	Quality requirement
NG2	Lossy context compression	Risk of missed vulnerabilities
NG3	Multiple local models	Complexity vs marginal benefit
NG4	Day-of-week scheduling	User rejected as not useful
NG5	Cost optimization over quality	Explicit user requirement

---

4. Resource Inventory

4.1 Hardware

Component	Specification	Role
GPU	NVIDIA RTX 5090 32GB VRAM	GLM-4.7-Flash inference
RAM	128GB DDR5	Model loading, context overflow
Storage	Gen5 NVMe 14.9 GB/s read	Fast model loading/swapping

4.2 Local Model: GLM-4.7-Flash

Attribute	Value
Full Name	GLM-4.7-Flash-UD-Q4_K_XL
Source	unsloth/GLM-4.7-Flash-GGUF
Parameters	30B total, ~3.6B active (MoE)
Quantization	Q4_K_XL
SWE-Bench Verified	59.2%
Context Window	Up to 200K tokens
License	MIT

VRAM by Context Length:

Context	VRAM	Use Case
32K	~20 GB	Small tasks
65K	~23 GB	Medium tasks
131K	~30 GB	Full epic (default)
200K	~36 GB	Requires CPU offload

Recommended Configuration: 131K context, ~30GB VRAM

4.3 Premium Sources

4.3.1 OpenAI Pro ($200/mo)

Attribute	Value
Models	Codex 5.2, GPT-4o, GPT-4o-mini
Best For	Security reviews, code-specific analysis
Access	API (api.openai.com)
Quota	Weekly limit with daily smoothing
Auth	OPENAI_API_KEY

4.3.2 Claude Max ($200/mo)

Attribute	Value
Models	Opus 4.5, Sonnet 4
Best For	Complex reasoning, architecture review
Access	API (api.anthropic.com), Claude Code
Quota	High usage limit
Auth	ANTHROPIC_API_KEY

4.3.3 GitHub Copilot Pro+ ($39/mo)

Attribute	Value
Models	Opus 4.5, Codex 5.2, Sonnet 4
Best For	Flexible routing, code-integrated
Access	Copilot Coding Agent
Quota	Generous with usage-based throttling
Auth	GitHub authentication

4.3.4 Google Ultra + Antigravity (~$25/mo)

Attribute	Value
Models	Opus 4.5, Gemini 3 Pro
Best For	Additional capacity, complex tasks
Access	Antigravity CLI
Quota	Separate from other sources
Auth	Google account

4.4 Quality Comparison

Model	SWE-Bench Verified	Role
Claude Opus 4.5	~74%	Premium - Complex/Security
GPT-5.2 / Codex 5.2	~72%	Premium - Security
Gemini 3 Pro	~68%	Premium - Routine/Complex
GLM-4.7-Flash	59.2%	Local - All preprocessing
Claude Sonnet 4	~55%	Premium - Routine
GPT-4o	~45%	Premium - Fallback

---

5. System Architecture

5.1 High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         FLOW-NEXT OPTIMIZED SYSTEM                           │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              USER / RALPH                                    │
│                                                                             │
│  /flow-next:interview  /flow-next:plan  /flow-next:work  /flow-next:review │
└───────────────────────────────────┬─────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│                         LOCAL PROCESSING LAYER                              │
│                         GLM-4.7-Flash @ 131K context                        │
│                         FREE, UNLIMITED                                     │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │  INTERVIEW  │  │    PLAN     │  │    WORK     │  │   REVIEW    │       │
│  │             │  │             │  │             │  │             │       │
│  │ • Question  │  │ • Scouts    │  │ • Re-anchor │  │ • Pre-screen│       │
│  │   drafting  │  │ • Spec draft│  │ • Complexity│  │ • Classify  │       │
│  │ • Spec help │  │ • Task break│  │   analysis  │  │ • Fingerprnt│       │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
│                                                                             │
└───────────────────────────────────┬─────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│                         QUOTA-AWARE ROUTER                                  │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Task Type    │  Available Sources        │  Selection              │   │
│  │───────────────┼───────────────────────────┼─────────────────────────│   │
│  │  SECURITY     │  Check OpenAI, Copilot    │  Codex 5.2 preferred    │   │
│  │  COMPLEX      │  Check Claude, Copilot,   │  Opus 4.5 preferred     │   │
│  │               │  Antigravity              │                         │   │
│  │  ROUTINE      │  Check all sources        │  Highest remaining      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└───────────────────────────────────┬─────────────────────────────────────────┘
                                    │
          ┌─────────────────────────┼─────────────────────────┐
          ▼                         ▼                         ▼
┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   OPENAI PRO    │       │   CLAUDE MAX    │       │    COPILOT /    │
│                 │       │                 │       │   ANTIGRAVITY   │
│   Codex 5.2     │       │   Opus 4.5      │       │                 │
│   GPT-4o        │       │   Sonnet 4      │       │   Opus / Codex  │
│                 │       │                 │       │   Gemini 3 Pro  │
└─────────────────┘       └─────────────────┘       └─────────────────┘

5.2 Data Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                              DATA FLOW                                       │
└─────────────────────────────────────────────────────────────────────────────┘

.flow/
├── epics/fn-N-xxx.json           # Epic metadata
├── tasks/fn-N-xxx.M.json         # Task metadata
├── specs/fn-N-xxx.md             # Epic specifications
├── tasks/fn-N-xxx.M.md           # Task specifications
├── config.json                    # Project configuration
├── meta.json                      # Flow metadata
│
├── state/                         # NEW: Optimization state
│   ├── review_state.json         # Fingerprints, blockers
│   ├── quota_state.json          # Multi-source quota tracking
│   └── metrics.json              # Telemetry
│
├── memory/                        # Existing memory system
│   ├── pitfalls.md
│   ├── conventions.md
│   └── decisions.md
│
└── cache/                         # NEW: Scout result caching
    ├── repo-scout/
    ├── practice-scout/
    └── docs-scout/

---

6. Phase 1: Interview

6.1 Overview

Interview is human-paced, gathering requirements through deep questioning (40+ questions). Token optimization focuses on using GLM-4.7-Flash for question generation and spec drafting.

6.2 Current vs Optimized

Aspect	Current	Optimized
Question generation	Premium	GLM-4.7-Flash
Spec drafting	Premium	GLM-4.7-Flash
Complex decisions	Premium	Premium (unchanged)
Token savings	-	30-50%

6.3 Interview Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                           INTERVIEW FLOW                                     │
└─────────────────────────────────────────────────────────────────────────────┘

/flow-next:interview <input>
          │
          ▼
┌─────────────────┐
│ PARSE INPUT     │
│                 │
│ • Epic ID       │
│ • Task ID       │
│ • File path     │
│ • Raw idea      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ GLM-4.7-Flash   │  ← LOCAL: Analyze input, identify question categories
│ QUESTION GEN    │
│                 │
│ Categories:     │
│ • Scope         │
│ • Technical     │
│ • Edge cases    │
│ • Acceptance    │
│ • Risks         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ HUMAN Q&A LOOP  │  ← AskUserQuestion tool, 40+ questions
│                 │
│ Group 2-4       │
│ related Qs      │
│ per tool call   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ GLM-4.7-Flash   │  ← LOCAL: Draft refined spec from answers
│ SPEC DRAFTING   │
│                 │
│ Sections:       │
│ • Problem       │
│ • Key decisions │
│ • Edge cases    │
│ • Acceptance    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ WRITE TO .flow/ │
│                 │
│ • epic set-plan │
│ • task set-spec │
│ • or file write │
└─────────────────┘

6.4 Question Generation Prompt

Generate interview questions for this {input_type}.

## Content
{content}

## Category: {category}

## Guidelines
- Dig deep on hidden complexity
- Surface unstated assumptions
- Identify edge cases the user hasn't considered
- Group related questions (2-4 per batch)
- Don't ask obvious questions—assume technical competence

Generate 5-10 questions for this category.
Format: One question per line, options in parentheses if applicable.

6.5 Spec Drafting Prompt

Draft a specification from this interview.

## Interview Q&A
{questions_and_answers}

## Output Format

# {Title}

## Problem
Clear problem statement (2-3 sentences)

## Key Decisions
- Decision 1: {choice} (rationale)
- Decision 2: {choice} (rationale)

## Edge Cases
- Edge case 1: How to handle
- Edge case 2: How to handle

## Open Questions
Items needing research during planning

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

---

7. Phase 2: Plan

7.1 Overview

Planning involves parallel scout agents analyzing the codebase, followed by spec writing and task breakdown. Optimization runs scouts locally with caching.

7.2 Current vs Optimized

Component	Current	Optimized
repo-scout	Premium	GLM-4.7-Flash (cached)
practice-scout	Premium	GLM-4.7-Flash (cached)
docs-scout	Premium	GLM-4.7-Flash (cached)
github-scout	Premium	Premium (needs API)
epic-scout	Premium	GLM-4.7-Flash
docs-gap-scout	Premium	GLM-4.7-Flash
Spec writing	Premium	GLM-4.7-Flash + Premium review
Task breakdown	Premium	GLM-4.7-Flash
Token savings	-	60-70%

7.3 Planning Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                            PLANNING FLOW                                     │
└─────────────────────────────────────────────────────────────────────────────┘

/flow-next:plan <input>
          │
          ▼
┌─────────────────┐
│ PARSE INPUT     │
│                 │
│ • Feature text  │
│ • Epic ID       │
│ • Task ID       │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PARALLEL SCOUT EXECUTION (GLM-4.7-Flash, cached)                            │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ repo-scout  │  │ practice-   │  │ docs-scout  │  │ epic-scout  │       │
│  │             │  │ scout       │  │             │  │             │       │
│  │ Codebase    │  │ Best        │  │ Existing    │  │ Epic deps   │       │
│  │ patterns    │  │ practices   │  │ docs        │  │             │       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘       │
│         │                │                │                │               │
│         └────────────────┴────────────────┴────────────────┘               │
│                                    │                                        │
│                          Scout Results Cache                                │
│                          (.flow/cache/*)                                    │
└────────────────────────────────────┬────────────────────────────────────────┘
                                     │
                                     ▼
                          ┌─────────────────┐
                          │ GLM-4.7-Flash   │  ← LOCAL: Draft epic spec
                          │ SPEC DRAFTING   │
                          │                 │
                          │ • Overview      │
                          │ • Approach      │
                          │ • Quick cmds    │
                          │ • Acceptance    │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ GLM-4.7-Flash   │  ← LOCAL: Create task breakdown
                          │ TASK BREAKDOWN  │
                          │                 │
                          │ • Dependencies  │
                          │ • Sizing (S/M)  │
                          │ • Ordering      │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ WRITE TO .flow/ │
                          │                 │
                          │ • Epic spec     │
                          │ • Task specs    │
                          │ • Dependencies  │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ PLAN REVIEW     │  ← Optional: /flow-next:plan-review
                          │ (if requested)  │
                          └─────────────────┘

7.4 Scout Caching

class ScoutCache:
    """Cache scout results to avoid redundant analysis."""
    
    cache_dir = Path(".flow/cache")
    
    # Cache TTL by scout type
    ttl_hours = {
        "repo-scout": 24,       # Invalidate on significant code changes
        "practice-scout": 168,  # 1 week (best practices don't change often)
        "docs-scout": 24,       # Invalidate on doc changes
        "epic-scout": 24,       # Invalidate on epic changes
    }
    
    def get(self, scout_type: str, query_hash: str) -> Optional[ScoutResult]:
        cache_file = self.cache_dir / scout_type / f"{query_hash}.json"
        
        if not cache_file.exists():
            return None
        
        data = json.loads(cache_file.read_text())
        cached_at = datetime.fromisoformat(data["cached_at"])
        
        # Check TTL
        if datetime.now() - cached_at > timedelta(hours=self.ttl_hours[scout_type]):
            return None
        
        # Check git hash for code-dependent scouts
        if scout_type in ["repo-scout", "docs-scout"]:
            if self._significant_changes_since(data["git_hash"]):
                return None
        
        return ScoutResult.from_dict(data["result"])
    
    def set(self, scout_type: str, query_hash: str, result: ScoutResult):
        cache_file = self.cache_dir / scout_type / f"{query_hash}.json"
        cache_file.parent.mkdir(parents=True, exist_ok=True)
        
        cache_file.write_text(json.dumps({
            "cached_at": datetime.now().isoformat(),
            "git_hash": self._current_git_hash(),
            "result": result.to_dict(),
        }, indent=2))

7.5 Spec Writing Guidelines

GLM-4.7-Flash drafts specs following these depth levels:

Size	Depth	Sections
SHORT (bugs, small)	Minimal	Problem, Acceptance, Context
STANDARD (most features)	Normal	Overview, Approach, Risks, Acceptance, Tests, Refs
DEEP (large/critical)	Full	Phases, Alternatives, NFRs, Architecture, Rollout, Metrics

Key Rule: Specs describe WHAT and WHY, not HOW. No implementation code in specs.

---

8. Phase 3: Work

8.1 Overview

Work phase implements tasks via worker subagents. Optimization uses GLM-4.7-Flash for re-anchoring and complexity-based model selection.

8.2 Current vs Optimized

Component	Current	Optimized
Re-anchoring	Premium context	GLM-4.7-Flash summary
Simple tasks	Premium	GLM-4.7-Flash (with escalation)
Complex tasks	Premium	Premium (unchanged)
Security tasks	Premium	Premium (unchanged)
Token savings	-	40-60%

8.3 Work Flow

┌─────────────────────────────────────��───────────────────────────────────────┐
│                             WORK FLOW                                        │
└─────────────────────────────────────────────────────────────────────────────┘

/flow-next:work <input>
          │
          ▼
┌─────────────────┐
│ SETUP QUESTIONS │
│                 │
│ • Branch mode   │
│ • Review mode   │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ TASK LOOP                                                                   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ flowctl ready --epic fn-N → Get next task                           │   │
│  └──────────────────────────────────┬──────────────────────────────────┘   │
│                                     │                                       │
│                                     ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ SPAWN WORKER (subagent with fresh context)                          │   │
│  │                                                                     │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ GLM-4.7-Flash   │ ← LOCAL: Create focused re-anchor summary     │   │
│  │  │ RE-ANCHOR       │                                                │   │
│  │  │                 │                                                │   │
│  │  │ • Task spec     │                                                │   │
│  │  │ • Epic context  │                                                │   │
│  │  │ • Memory files  │                                                │   │
│  │  │ • Git state     │                                                │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │           ▼                                                         │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ GLM-4.7-Flash   │ ← LOCAL: Analyze task complexity              │   │
│  │  │ CLASSIFY        │                                                │   │
│  │  │                 │                                                │   │
│  │  │ • LOW: Local    │                                                │   │
│  │  │ • MED: Hybrid   │                                                │   │
│  │  │ • HIGH: Premium │                                                │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │     ┌─────┴─────────────────┐                                       │   │
│  │     ▼                       ▼                                       │   │
│  │  ┌──────────────┐    ┌──────────────┐                               │   │
│  │  │ LOW/MEDIUM   │    │ HIGH         │                               │   │
│  │  │              │    │              │                               │   │
│  │  │ GLM-4.7-Flash│    │ Premium      │                               │   │
│  │  │ implements   │    │ implements   │                               │   │
│  │  │              │    │ (Opus/Codex) │                               │   │
│  │  │ Escalate if  │    │              │                               │   │
│  │  │ stuck/unsure │    │              │                               │   │
│  │  └──────┬───────┘    └──────┬───────┘                               │   │
│  │         │                   │                                       │   │
│  │         └─────────┬─────────┘                                       │   │
│  │                   │                                                 │   │
│  │                   ▼                                                 │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ COMMIT          │ ← Conventional commits                        │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │           ▼                                                         │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ REVIEW          │ ← See Phase 4                                  │   │
│  │  │ (if enabled)    │                                                │   │
│  │  └────────┬────────┘                                                │   │
│  │           │                                                         │   │
│  │           ▼                                                         │   │
│  │  ┌─────────────────┐                                                │   │
│  │  │ flowctl done    │ ← Complete task                                │   │
│  │  └─────────────────┘                                                │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                     │                                       │
│                          Next task or Quality phase                         │
└─────────────────────────────────────────────────────────────────────────────┘

8.4 Complexity Classification

class TaskComplexityAnalyzer:
    """Analyze task complexity for model selection."""
    
    def classify(self, task: Task, epic: Epic) -> Complexity:
        indicators = {
            "security_sensitive": self._is_security_sensitive(task),
            "architectural": self._is_architectural(task),
            "concurrency": self._involves_concurrency(task),
            "unfamiliar_patterns": self._uses_unfamiliar_patterns(task),
            "large_scope": task.size in ["L", "XL"],
            "many_files": len(task.files) > 5,
            "cross_module": self._is_cross_module(task),
        }
        
        high_count = sum(indicators.values())
        
        # Security always requires premium
        if indicators["security_sensitive"]:
            return Complexity.HIGH
        
        # Multiple indicators = complex
        if high_count >= 3:
            return Complexity.HIGH
        elif high_count >= 1:
            return Complexity.MEDIUM
        else:
            return Complexity.LOW
    
    def _is_security_sensitive(self, task: Task) -> bool:
        patterns = ["auth", "crypto", "password", "secret", "token", "session"]
        return any(p in str(task.files).lower() for p in patterns)

8.5 Re-Anchor Prompt

Create implementation context for task {task_id}.

## Task Specification
{task_spec}

## Epic Context
{epic_spec}

## Memory (pitfalls, conventions, decisions)
{memory_content}

## Git State
{git_status}
{git_log_5}

## Output

Create a focused implementation summary:

### Acceptance Criteria
- Bullet points from spec

### Files to Modify
- List with brief rationale

### Relevant Patterns
- From memory or epic

### Dependencies
- Other tasks, external

### Test Requirements
- From spec

Keep it focused. Worker will read full spec if needed.

---

9. Phase 4: Review

9.1 Overview

Review phase is the highest token consumer. Optimization introduces a multi-stage pipeline with local pre-screening, fingerprint deduplication, task classification, and multi-source routing.

9.2 Current vs Optimized

Aspect	Current	Optimized
Pre-screening	None	GLM-4.7-Flash catches 60%+
Fingerprinting	None	Skip unchanged diffs
Classification	None	Route by task type
Sources	Single	4-source pooling
Prompts	3000 tokens	500 tokens
Context	Sometimes compressed	Always full (no lossy compression)
Token savings	-	70-80%

9.3 Review Pipeline

┌─────────────────────────────────────────────────────────────────────────────┐
│                           REVIEW PIPELINE                                    │
└─────────────────────────────────────────────────────────────────────────────┘

                              Review Request
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STAGE 1: GATES                                                              │
│ Deterministic checks (FREE)                                                 │
│                                                                             │
│   lint ──► build ──► typecheck                                             │
│                                                                             │
│   FAIL → Fix before proceeding                                              │
│   PASS → Continue                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STAGE 2: PRE-SCREEN                                                         │
│ GLM-4.7-Flash @ 131K context (FREE)                                         │
│                                                                             │
│   Full context review for obvious issues:                                   │
│   • Missing imports                                                         │
│   • Undefined variables                                                     │
│   • Obvious null access                                                     │
│   • Logic errors                                                            │
│   • Missing returns                                                         │
│   • Spec violations                                                         │
│                                                                             │
│   NEEDS_WORK (obvious) → Fix locally, re-run (up to 3 iterations)          │
│   LOOKS_GOOD → Continue to premium                                          │
│   UNCERTAIN → Continue to premium with observations                         │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STAGE 3: FINGERPRINT                                                        │
│ SHA-256 diff hash (FREE)                                                    │
│                                                                             │
│   fingerprint = sha256(normalize(git diff base..HEAD))                      │
│                                                                             │
│   UNCHANGED since last NEEDS_WORK → Block until blocker files touched      │
│   CHANGED → Continue                                                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STAGE 4: CLASSIFY                                                           │
│ GLM-4.7-Flash (FREE)                                                        │
│                                                                             │
│   Analyze changed files and diff content:                                   │
│                                                                             │
│   SECURITY → auth, crypto, credentials, tokens, passwords                   │
│   COMPLEX  → architecture, concurrency, core logic, database                │
│   ROUTINE  → tests, docs, simple fixes, config                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STAGE 5: ROUTE                                                              │
│ Quota-aware selection                                                       │
│                                                                             │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │ Task Type │ Priority Order                                          │  │
│   │───────────┼─────────────────────────────────────────────────────────│  │
│   │ SECURITY  │ OpenAI(Codex5.2) → Copilot(Codex5.2) → Claude(Opus)    │  │
│   │ COMPLEX   │ Claude(Opus) → Copilot(Opus) → Antigravity(Opus/Gemini)│  │
│   │ ROUTINE   │ Highest remaining quota → Sonnet → Gemini              │  │
│   └─────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│   Check quota_state.json for each source                                    │
│   Skip throttled or <5% remaining                                           │
│   Select best available                                                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STAGE 6: PREMIUM REVIEW                                                     │
│ Full context, lean prompt                                                   │
│                                                                             │
│   Context (NO lossy compression):                                           │
│   • Changed files (full content)                                            │
│   • Direct imports (full content)                                           │
│   • Test files (full content)                                               │
│   • Full diff                                                               │
│   • Task/epic specs                                                         │
│   • Local pre-screen observations                                           │
│                                                                             │
│   Lean prompt (~500 tokens):                                                │
│   • Task type focus areas                                                   │
│   • Critical/Major issues only                                              │
│   • No suggestions, no explanations                                         │
│   • Verdict required: SHIP or NEEDS_WORK                                    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                           SHIP or NEEDS_WORK
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
                  SHIP                        NEEDS_WORK
               (complete)                          │
                                                   ▼
                                          Save blockers,
                                          update fingerprint,
                                          return issues

9.4 Pre-Screen Prompt

Pre-screen this code change before premium review.

## Task
{task_spec}

## Epic Context
{epic_spec}

## Diff
{full_diff}

## Changed Files
{changed_files_content}

## Instructions

Look for issues that should be fixed before expensive premium review:
1. Missing imports/exports
2. Undefined variables
3. Obvious null/undefined access
4. Clear logic errors
5. Missing return statements
6. Spec violations (check acceptance criteria)
7. Test failures (if tests included)

## Output

If obvious issues found:
<verdict>NEEDS_WORK</verdict>
<confidence>HIGH</confidence>
<issues>
- FILE:LINE - DESCRIPTION
</issues>

If ready for premium review:
<verdict>LOOKS_GOOD</verdict>
<observations>
Optional notes for premium reviewer
</observations>

If uncertain:
<verdict>UNCERTAIN</verdict>
<reason>What you're unsure about</reason>

Be conservative. LOOKS_GOOD or UNCERTAIN when in doubt.

9.5 Classification Prompt

Classify this code review task.

## Files Changed
{file_list}

## Diff Stats
{diff_stat}
{lines_changed} lines changed

## Task Title
{task_title}

## Rules

SECURITY (any of):
- Authentication, authorization, access control
- Cryptography, hashing, encryption
- Credentials, passwords, secrets, tokens
- Session management, JWT, OAuth
- Input validation for security
- Data exposure risks

COMPLEX (any of):
- Core system architecture
- Concurrency, parallelism, async
- Database schema, migrations
- Major refactoring (>500 lines)
- Distributed systems
- Performance-critical paths

ROUTINE (everything else):
- Tests, documentation
- Simple bug fixes
- Configuration changes
- Formatting, style
- Dependency updates

## Output

One word: SECURITY, COMPLEX, or ROUTINE

9.6 Premium Review Prompt (Lean)

Review task {task_id} for production readiness.

## Task Type: {task_type}
{type_specific_focus}

## Local Pre-Screen
{local_observations}

## Diff
{full_diff}

## Changed Files
{changed_files_content}

## Context Files
{import_files_content}

## Output

Critical/Major issues only:
- SEVERITY: CRITICAL or MAJOR
- FILE:LINE
- PROBLEM (one sentence)

Verdict:
<verdict>SHIP</verdict> or <verdict>NEEDS_WORK</verdict>

No suggestions. No minor issues. No explanations.

Type-Specific Focus:

Type	Focus
SECURITY	Injection, auth bypass, data exposure, credential handling, input validation
COMPLEX	Race conditions, deadlocks, resource leaks, architectural violations, scalability
ROUTINE	Correctness vs spec, obvious bugs, test coverage

---

10. Local Model Infrastructure

10.1 Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      LOCAL MODEL INFRASTRUCTURE                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ llama-swap (Port 8080)                                                      │
│                                                                             │
│ Proxy that manages llama.cpp model loading/unloading                        │
│                                                                             │
│ Features:                                                                    │
│ • Anthropic/OpenAI API compatibility (for Claude Code integration)          │
│ • Model hot-swapping without restart                                        │
│ • GPU memory release when idle                                              │
│ • Health checks and monitoring                                              │
│                                                                             │
│ Endpoints:                                                                   │
│   /v1/chat/completions  → OpenAI-compatible                                 │
│   /v1/messages          → Anthropic-compatible                              │
│   /completion           → llama.cpp native                                  │
│   /health               → Health check                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ llama-server                                                                │
│ GLM-4.7-Flash-UD-Q4_K_XL                                                    │
│                                                                             │
│ Configuration:                                                               │
│ • Context: 131072 tokens (131K)                                             │
│ • GPU layers: 99 (all on GPU)                                               │
│ • KV cache: Q4_0 quantized                                                  │
│ • Flash attention: enabled                                                   │
│ • Memory mapping: enabled (NVMe)                                            │
│ • Threads: 8                                                                 │
│                                                                             │
│ Resources:                                                                   │
│ • VRAM: ~30GB                                                               │
│ • Speed: 60-100 tok/s                                                       │
└─────────────────────────────────────────────────────────────────────────────┘

10.2 llama-swap Configuration

# llama-swap.yaml
listen: 0.0.0.0:8080

models:
  glm-4.7-flash:
    cmd: >
      llama-server
      -m /models/GLM-4.7-Flash-UD-Q4_K_XL.gguf
      -ngl 99
      -c 131072
      --cache-type-k q4_0
      --cache-type-v q4_0
      -fa
      --mmap
      -t 8
      --host 127.0.0.1
      --port 9001
    proxy: http://127.0.0.1:9001
    ttl: 600  # Unload after 10 min idle
    healthcheck:
      endpoint: /health
      interval: 30

# Aliases for Claude Code / Codex CLI compatibility
aliases:
  claude-3-5-sonnet-20241022: glm-4.7-flash
  claude-3-opus-20240229: glm-4.7-flash
  gpt-4: glm-4.7-flash
  gpt-4-turbo: glm-4.7-flash

healthcheck:
  interval: 30
  timeout: 5

logging:
  level: info
  file: /var/log/llama-swap.log

10.3 Startup Script

#!/bin/bash
# start-local-model.sh

set -e

MODELS_DIR="${MODELS_DIR:-$HOME/models}"
CONFIG_DIR="${CONFIG_DIR:-$HOME/.config/flow-next}"
LOG_DIR="${LOG_DIR:-/tmp/flow-next}"

mkdir -p "$LOG_DIR"

echo "=== Starting GLM-4.7-Flash ==="
echo "Model: GLM-4.7-Flash-UD-Q4_K_XL"
echo "Context: 131K tokens"
echo "VRAM: ~30GB"
echo ""

# Check model exists
MODEL_PATH="$MODELS_DIR/GLM-4.7-Flash-UD-Q4_K_XL.gguf"
if [[ ! -f "$MODEL_PATH" ]]; then
    echo "Model not found at $MODEL_PATH"
    echo "Download with:"
    echo "  huggingface-cli download unsloth/GLM-4.7-Flash-GGUF \\"
    echo "    GLM-4.7-Flash-UD-Q4_K_XL.gguf --local-dir $MODELS_DIR"
    exit 1
fi

# Kill existing
pkill -f "llama-swap" 2>/dev/null || true
pkill -f "llama-server.*GLM-4.7" 2>/dev/null || true
sleep 2

# Start llama-swap
echo "[1/2] Starting llama-swap..."
llama-swap -c "$CONFIG_DIR/llama-swap.yaml" \
    2>&1 > "$LOG_DIR/llama-swap.log" &

sleep 2

# Wait for llama-swap
echo "[2/2] Waiting for server..."
for i in {1..60}; do
    if curl -s http://localhost:8080/health > /dev/null 2>&1; then
        break
    fi
    sleep 1
done

if ! curl -s http://localhost:8080/health > /dev/null 2>&1; then
    echo "Failed to start llama-swap"
    cat "$LOG_DIR/llama-swap.log"
    exit 1
fi

# Pre-warm model
echo "Pre-warming model..."
curl -s http://localhost:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model": "glm-4.7-flash", "messages": [{"role": "user", "content": "ready"}], "max_tokens": 1}' \
    > /dev/null

echo ""
echo "=== GLM-4.7-Flash Ready ==="
echo "Endpoint: http://localhost:8080"
echo "Context: 131K tokens"
echo "Speed: 60-100 tok/s"
echo ""
echo "For Claude Code integration:"
echo "  export ANTHROPIC_BASE_URL=http://localhost:8080/v1"
echo "  export ANTHROPIC_API_KEY=local"

10.4 Model Download

#!/bin/bash
# download-model.sh

MODELS_DIR="${MODELS_DIR:-$HOME/models}"
mkdir -p "$MODELS_DIR"

echo "Downloading GLM-4.7-Flash-UD-Q4_K_XL..."

huggingface-cli download unsloth/GLM-4.7-Flash-GGUF \
    GLM-4.7-Flash-UD-Q4_K_XL.gguf \
    --local-dir "$MODELS_DIR"

echo "Model downloaded to $MODELS_DIR/GLM-4.7-Flash-UD-Q4_K_XL.gguf"

10.5 Health Check

#!/bin/bash
# check-local-model.sh

echo "Checking GLM-4.7-Flash status..."

# Check llama-swap
if curl -s http://localhost:8080/health > /dev/null 2>&1; then
    echo "✓ llama-swap: Running"
else
    echo "✗ llama-swap: Not running"
    exit 1
fi

# Check model loaded
RESPONSE=$(curl -s http://localhost:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model": "glm-4.7-flash", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 5}')

if echo "$RESPONSE" | grep -q "content"; then
    echo "✓ GLM-4.7-Flash: Loaded and responding"
else
    echo "✗ GLM-4.7-Flash: Not responding"
    echo "$RESPONSE"
    exit 1
fi

# Check VRAM
if command -v nvidia-smi &> /dev/null; then
    VRAM=$(nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits)
    echo "✓ VRAM: ${VRAM}MB used"
fi

echo ""
echo "Local model ready for flow-next"

---

11. Multi-Source Premium Orchestration

11.1 Quota Tracking

# quota_tracker.py

from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
import json

@dataclass
class QuotaStatus:
    source: str
    remaining_pct: float  # 0.0 to 1.0
    is_throttled: bool
    last_request: datetime
    requests_today: int
    tokens_today: int


class QuotaTracker:
    """Track quota usage across all premium sources."""
    
    def __init__(self, state_file: Path = Path(".flow/state/quota_state.json")):
        self.state_file = state_file
        self.state = self._load()
    
    def _load(self) -> dict:
        if self.state_file.exists():
            return json.loads(self.state_file.read_text())
        return {"sources": {}, "last_updated": None}
    
    def _save(self):
        self.state_file.parent.mkdir(parents=True, exist_ok=True)
        self.state["last_updated"] = datetime.now().isoformat()
        self.state_file.write_text(json.dumps(self.state, indent=2))
    
    def get_status(self, source: str) -> QuotaStatus:
        """Get current quota status for a source."""
        s = self.state.get("sources", {}).get(source, {})
        return QuotaStatus(
            source=source,
            remaining_pct=s.get("remaining_pct", 1.0),
            is_throttled=s.get("is_throttled", False),
            last_request=datetime.fromisoformat(s["last_request"]) if s.get("last_request") else None,
            requests_today=s.get("requests_today", 0),
            tokens_today=s.get("tokens_today", 0),
        )
    
    def record_usage(self, source: str, tokens: int, was_throttled: bool = False):
        """Record usage for a source."""
        if "sources" not in self.state:
            self.state["sources"] = {}
        
        if source not in self.state["sources"]:
            self.state["sources"][source] = {}
        
        s = self.state["sources"][source]
        s["last_request"] = datetime.now().isoformat()
        s["requests_today"] = s.get("requests_today", 0) + 1
        s["tokens_today"] = s.get("tokens_today", 0) + tokens
        s["is_throttled"] = was_throttled
        
        # Estimate remaining based on usage patterns
        s["remaining_pct"] = self._estimate_remaining(source, s)
        
        self._save()
    
    def mark_throttled(self, source: str):
        """Mark a source as throttled."""
        if source in self.state.get("sources", {}):
            self.state["sources"][source]["is_throttled"] = True
            self._save()
    
    def clear_throttle(self, source: str):
        """Clear throttle flag for a source."""
        if source in self.state.get("sources", {}):
            self.state["sources"][source]["is_throttled"] = False
            self._save()
    
    def get_available_sources(self, task_type: str) -> list[tuple[str, str]]:
        """Get available sources for task type, sorted by preference."""
        routing = self._get_routing(task_type)
        
        available = []
        for source, model in routing:
            status = self.get_status(source)
            if not status.is_throttled and status.remaining_pct > 0.05:
                available.append((source, model))
        
        return available
    
    def _get_routing(self, task_type: str) -> list[tuple[str, str]]:
        """Get routing priority for task type."""
        routes = {
            "security": [
                ("openai_pro", "codex-5.2"),
                ("copilot", "codex-5.2"),
                ("claude_max", "opus-4.5"),
                ("copilot", "opus-4.5"),
                ("antigravity", "opus-4.5"),
            ],
            "complex": [
                ("claude_max", "opus-4.5"),
                ("copilot", "opus-4.5"),
                ("antigravity", "opus-4.5"),
                ("antigravity", "gemini-3-pro"),
                ("openai_pro", "codex-5.2"),
            ],
            "routine": [
                ("_lowest_quota", ""),  # Special: select highest remaining
                ("copilot", "sonnet-4"),
                ("claude_max", "sonnet-4"),
                ("antigravity", "gemini-3-pro"),
                ("openai_pro", "gpt-4o"),
            ],
        }
        return routes.get(task_type, routes["routine"])
    
    def _estimate_remaining(self, source: str, state: dict) -> float:
        """Estimate remaining quota (heuristic)."""
        # This is approximate—real quotas require API queries
        tokens = state.get("tokens_today", 0)
        
        # Estimated daily limits (conservative)
        limits = {
            "openai_pro": 2_000_000,
            "claude_max": 5_000_000,
            "copilot": 3_000_000,
            "antigravity": 3_000_000,
        }
        
        limit = limits.get(source, 1_000_000)
        return max(0.0, 1.0 - (tokens / limit))

11.2 Premium Router

# premium_router.py

from dataclasses import dataclass
from enum import Enum

class TaskType(Enum):
    SECURITY = "security"
    COMPLEX = "complex"
    ROUTINE = "routine"


@dataclass
class RoutingDecision:
    source: str
    model: str
    reason: str


class PremiumRouter:
    """Route reviews to best available premium source."""
    
    def __init__(self, quota_tracker: QuotaTracker, backends: dict):
        self.quota = quota_tracker
        self.backends = backends
    

[gmickel]

Such a great write up, thanks so much @clairernovotny . Will be looking into this both for Flow-Next and the upcoming orchestration platform which already supports an unlimited number of backends! Leaving open for now