> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Planning Landscape

> Five kinds of planning in the AI tooling landscape and where FIM One fits.

## Five kinds of "planning" in the AI tooling landscape

The word "planning" is overloaded. At least five distinct approaches exist today, and they solve different problems:

| Approach                    | Plan format                                     | Execution                            | Approval                             | Core value                                  |
| --------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------------- |
| **Implicit model planning** | Internal chain-of-thought                       | Single inference pass                | None                                 | The model thinks through steps on its own   |
| **Claude Code plan mode**   | Markdown document                               | Serial                               | Human reviews before execution       | Align on approach before touching code      |
| **Claude Code Teams**       | Task list with dependency edges                 | **Concurrent** (multi-agent)         | Human approves plan, then autonomous | Dynamic agent pool + parallel execution     |
| **Kiro spec-driven dev**    | Structured spec (requirements + design + tasks) | Serial                               | Human reviews spec                   | Traceable requirements, acceptance criteria |
| **FIM One DAG**             | JSON dependency graph                           | **Concurrent** (single orchestrator) | Automatic (PlanAnalyzer)             | Parallel execution + runtime scheduling     |

The first two are **design-time** planning — they produce a plan *before* work begins, and a human (or the model itself) follows it step by step. The last three introduce **runtime** planning — execution graphs are generated and scheduled programmatically, with independent branches running in parallel. The difference is *who* executes: Claude Code Teams spawns autonomous agents; FIM One DAG dispatches steps within a single orchestrator.

These approaches are not competitors; they are complementary layers. A Kiro-style spec can define *what* to build, while a FIM One DAG can schedule *how* to execute the subtasks concurrently. Claude Code's plan mode ensures a human agrees with the approach; FIM One's PlanAnalyzer verifies the outcome automatically.

## Three-Layer Nesting: The Full-Power Architecture

Both Claude Code Teams and FIM One DAG, at full capacity, exhibit a **three-layer nested architecture**:

```mermaid theme={null}
flowchart TB
    subgraph L1["Layer 1: Human-in-the-Loop"]
        direction TB
        H["User approves plan / confirms direction"]

        subgraph L2["Layer 2: DAG Orchestration"]
            direction TB
            D1["Task graph with dependency edges"]
            D2["Parallel dispatch of independent branches"]
            D1 --> D2

            subgraph L3A["Layer 3: ReAct Loop"]
                R1["Perceive → Reason → Act → Observe"]
            end

            subgraph L3B["Layer 3: ReAct Loop"]
                R2["Perceive → Reason → Act → Observe"]
            end

            subgraph L3C["Layer 3: ReAct Loop"]
                R3["Perceive → Reason → Act → Observe"]
            end

            D2 --> L3A & L3B & L3C
        end

        H --> L2
    end
```

* **Layer 1 — Human gate**: User reviews the plan and approves before execution begins.
* **Layer 2 — DAG orchestration**: The approved plan is decomposed into tasks with dependency edges. Independent tasks run in parallel; downstream tasks wait for their blockers to resolve.
* **Layer 3 — ReAct inner loop**: Each task is executed by an agent running a full ReAct cycle (Perceive → Reason → Act → Observe), capable of multi-step reasoning, tool use, and autonomous retry.

The key insight: **Claude Code Teams and FIM One DAG implement the same three layers, just with different Layer 2 mechanics** — message-passing vs dependency-edge resolution.

## Full-Power Runtime: FIM One vs Claude Code Teams

Both are genuine Agents — the core loop is identical: **Perceive → Reason → Act → Feedback**. The difference lies in how they orchestrate parallel work at full capacity.

| Dimension                 | Claude Code Teams                                                   | FIM One DAG                                                         |
| ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Parallel model**        | Leader spawns SubAgents, assigns tasks via messages                 | Topological sort auto-parallelizes independent steps                |
| **Task graph**            | TaskList with `blockedBy` / `blocks` edges (dynamic DAG)            | Static JSON DAG with `depends_on` edges                             |
| **Coordination**          | Explicit message passing (SendMessage / Broadcast)                  | Implicit dependency edges — no messages, just data flow             |
| **Agent lifecycle**       | Dynamic pool — agents spawned on demand, shut down when done        | Fixed step executors — one LLM call per step                        |
| **Feedback & correction** | Each SubAgent retries autonomously; Leader re-assigns on failure    | PlanAnalyzer evaluates outcomes → Re-Planning loop (up to 3 rounds) |
| **Human involvement**     | Plan mode approval, then autonomous execution                       | Fully automatic — PlanAnalyzer decides pass/replan                  |
| **Context management**    | Each SubAgent gets isolated context window (no cross-contamination) | Shared DbMemory + LLM Compact across all steps                      |
| **Token economics**       | `N agents × per-agent tokens` — time↓ tokens↑ (multiplicative cost) | Sequential or shallow-parallel — lower total tokens                 |
| **Scaling pattern**       | Add more SubAgents (horizontal, message-coupled)                    | Add more DAG branches (horizontal, dependency-coupled)              |
| **Best suited for**       | Diverse, loosely-related tasks (research + code + test)             | Structured workflows with clear data dependencies                   |

### Real-World Benchmark: v0.5 RAG System

Claude Code Teams built FIM One's entire v0.5 RAG subsystem in a single session:

* **8 phases**: Embedding → Reranker → Loaders → Chunking → VectorStore → Retrieval → KB Backend → Frontend + Docs
* **46 tests** passing, frontend build clean
* **Wall time**: \~5 minutes
* **Token cost**: \~100k tokens per agent task × 8+ tasks ≈ 800k+ total tokens
* **Dependency edges**: Phase 5 depends on Phase 4 + 1b; Phase 6 depends on Phase 5 + 2 + 3 — a genuine DAG

This demonstrates the core trade-off: **time parallelism at the cost of token multiplication**. Claude Code Teams trades compute dollars for developer hours.

### Converging, Not Competing

The boundary between "team collaboration" and "pipeline scheduling" is blurring:

* **Claude Code Teams' `blockedBy`/`blocks` IS a DAG** — tasks have explicit dependency edges, and the leader dispatches newly-unblocked tasks as predecessors complete. This is topological scheduling with extra steps (messages).
* **FIM One's DAG could benefit from agent autonomy** — instead of single LLM calls per step, letting each step run a full ReAct loop would handle complex sub-tasks better.

**Takeaway:** Same Agent essence, converging parallel philosophies. Claude Code follows a **team collaboration** model — a Leader delegates to Workers who communicate via messages. FIM One follows a **pipeline scheduling** model — a DAG Executor dispatches steps based on dependency resolution. In practice, both implement dependency-driven parallel execution; the difference is coordination overhead (messages vs edges) and token economics (isolated contexts vs shared memory). The optimal architecture likely combines both: DAG scheduling for structured pipelines, agent pools for tasks that need autonomous multi-step reasoning.

## Structured Output Degradation

All structured LLM call sites in the DAG pipeline (Planner, Analyzer, Tool Selection) use a unified `structured_llm_call()` utility that implements a 3-level degradation chain:

| Level          | Condition                    | How it works                                                                     |
| -------------- | ---------------------------- | -------------------------------------------------------------------------------- |
| **Native FC**  | `llm.abilities["tool_call"]` | Forces a virtual tool call; extracts from `tool_calls[0].arguments`              |
| **JSON Mode**  | `llm.abilities["json_mode"]` | Sets `response_format={"type":"json_object"}`; parses with `extract_json()`      |
| **Plain text** | always available             | Parses free-form content with `extract_json()`, then optional `regex_fallback()` |

Each text-based level retries once with a reformat prompt before falling to the next. The result is a `StructuredCallResult` containing the parsed value, which extraction level succeeded, and accumulated token usage.

This design means the same prompt works reliably across GPT-4 (native FC), Claude (JSON mode), and local models (plain text), with consistent error handling and retry logic in one place instead of scattered across four call sites.

## Three Execution Layers: Control Spectrum

The five planning approaches above describe the landscape. Within FIM One itself, three execution layers offer a **control spectrum** — from full human control to full AI autonomy:

| Layer               | Graph defined by                      | Graph exists when? | Best for                                                                                          |
| ------------------- | ------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
| **Workflow Engine** | User (visual canvas / JSON blueprint) | Design time        | Deterministic processes, compliance/audit trails, cron-scheduled automation, non-AI orchestration |
| **DAGPlanner**      | LLM (auto-decomposes the goal)        | Runtime            | Decomposable multi-step tasks with clear sub-task boundaries                                      |
| **ReAct Agent**     | None (iterative loop)                 | Never — no graph   | Exploratory, conversational, or iterative-refinement tasks                                        |

The design principle: **give users exactly as much control as they want**.

* Need to prove every loan approval passes five specific steps? → Workflow.
* Need to research three topics in parallel then synthesize? → DAG.
* Need to draft and refine until satisfied? → Agent.
* Not sure? → `execution_mode: "auto"` lets the LLM classify the query and route to DAG or ReAct at runtime.

This layering is what separates FIM One from single-paradigm tools:

* **Dify** offers only the Workflow layer (static visual DAGs).
* **LangGraph** offers only a code-level graph DSL (developer-defined topology, dynamic routing — structurally equivalent to visual workflows but requiring Python).
* **Manus** offers only the Agent layer (autonomous execution, no user-defined structure).

FIM One covers all three layers, plus automatic routing between them. The abstraction progression — user-defined graph → LLM-generated graph → no graph at all — mirrors a broader industry trend: as models grow more capable, explicit orchestration structures become optional rather than mandatory.