Ferment

Ferment is Kimchi's autonomous project mode. Describe a goal — "Build Tetris", "Add Google OAuth login", "Migrate the API to async/await" — and the harness breaks it into phases, executes each one using specialised subagent workers, grades the results, and picks up exactly where it left off if a session ends.

Where regular chat mode handles one-off tasks, Ferment handles projects: multi-step work that spans sessions and benefits from structured planning, execution tracking, and persistent context.

Ferment runs with --yolo permissions — the agent reads, writes, and executes shell commands without prompting for approval. Permissions are elevated as soon as you approve ferment creation (from the draft state onward), so the scoping and execution flow can proceed without interruption. You shape the work during scoping and at phase boundaries (in manual mode), not at individual tool calls.

The core idea

Every ferment is a single JSON file on disk. The harness reads the file at session start, a deterministic engine decides what to do next, and every action — activating a phase, completing a step, recording a decision — updates the file immediately. If the process crashes or the session ends, the next session resumes from exactly where it left off.

The plan is the state. There is no separate execution log, no external database, and no synchronisation protocol. The file is the complete, authoritative record of the project.

Concepts

A ferment is organised into a hierarchy:

Ferment  ← the project ("Build Tetris")
│
├── Scoping   (goal, success criteria, constraints, assumptions)
├── Decisions (architectural choices that shaped the work)
├── Memories  (conventions, gotchas, patterns discovered along the way)
│
└── Phases  ← milestones (1–7 recommended)
    │
    └── Steps  ← concrete tasks (3–6 per phase)

Ferment — the top-level project container. Each ferment has a name, scoping answers, and one or more phases.

Phases — milestones that organise work into logical slices. Phases execute sequentially by default, or in parallel when grouped (see Parallel phases below).

Steps — concrete tasks within a phase. Each step has a description, an optional verification command, and a worker model assignment. Steps are executed by subagent workers and graded on completion.

Lifecycle

A ferment moves through a predictable set of statuses:

Phases follow their own lifecycle: planned → active → completed / skipped / failed. Steps follow: pending → running → done / verified / skipped / failed.

When a ferment transitions from running to having no active phases, it returns to the planned state, ready for the next phase to be activated.

Starting a ferment

There are two ways to start a ferment:

• Slash command — Run /ferment (or /ferment new "Name") from the Kimchi prompt. The agent opens an interactive picker and walks you through scoping.
• Agent-initiated — When the agent detects that your request involves substantive, multi-step work (a project build, codebase audit, migration, etc.), it offers to start a ferment on your behalf. The offer appears as a structured yes/no question. If you accept, the agent creates the draft and begins scoping automatically. In --yolo mode, the agent skips the question and starts the ferment directly.

Both paths lead to the same scoping flow described below.

Scoping

When a ferment is created, the agent follows a structured orient-interview-plan scoping flow:

1. Orient — The agent does a lightweight scan of the project — file listing, README, config files, and short entrypoint snippets — to build an initial mental model. It identifies unknowns and assumptions but does not ask questions yet. For greenfield projects with no existing codebase, this step is noted and skipped.
2. Interview — The agent asks you about the unknowns identified during orientation. Questions are asked in iterative rounds: after each round of answers, the agent reflects on how the answers change its understanding and whether new questions have emerged. Questions are only asked when genuinely needed — ambiguous intent, assumptions that could be wrong, or decisions only you can make. For broad discovery or planning requests, the agent may ask which improvement areas to include. If the intent is clear, the agent moves on without manufacturing questions.
3. Completion criteria — The agent drafts concrete, testable criteria for what "done" looks like and confirms them with you before proceeding. This is a hard gate — scoping cannot continue until you approve the criteria.
4. Codebase exploration — For existing codebases, the agent investigates implementation-specific details using targeted reads and Explore subagents, focusing on unknowns that remain after the interview. Skipped for greenfield tasks with no existing codebase.
5. Plan proposal — The agent synthesises everything into a structured scope: a concise title, goal, success criteria, constraints, assumptions, and 1–7 phases.

Once you confirm the plan, the ferment transitions to planned.

Continuation policy

Continuation policy controls how the ferment advances between phases:

Switch at any time:

/ferment manual
/ferment auto

Pause, resume, and exit are separate lifecycle controls — /ferment pause halts the lifecycle, /ferment resume continues it using whichever policy is active. /ferment exit leaves Ferment mode without deleting or abandoning the ferment; planned or running work is paused first, active Ferment UI and tools are cleared, and you can later select it from /ferment list or /ferment switch.

Grading

After every step and phase completes, an autonomous judge evaluates the work and assigns a letter grade:

Grades appear in the dashboard widget and the /ferment progress overlay. They're also injected into the planner's context so later phases can learn from earlier results.

Decisions and memories

The planner captures knowledge that persists across phases and sessions:

Decisions are architectural or design choices:

D001: Use Canvas API — better performance than DOM for grid rendering
D002: Single game loop at 60fps — simpler than event-driven approach

Memories are conventions, gotchas, and patterns:

M001 [gotcha]: requestAnimationFrame drops frames if loop takes >16ms
M002 [convention]: All piece coordinates are relative to their bounding box
M003 [pattern]: Use Uint8Array for grid — faster collision detection

Both are automatically injected into every phase activation — so Phase 4 knows what Phase 1 decided without repeating context.

Parallel phases

Phases with the same parallel group number activate and run simultaneously. When scoping, the agent may propose parallel phases where the work is independent:

Phase 3: "Backend API"    (parallel group 1)
Phase 4: "Frontend UI"    (parallel group 1)
Phase 5: "Deploy"         (sequential — runs after both complete)

The planner activates both group-1 phases at once, spawns subagents for each concurrently, and only moves to Phase 5 once both are done. Parallel phases are marked with ∥ in the dashboard.

Dashboard and progress tracking

The dashboard widget is always visible above the editor while a ferment is running:

Build Tetris  [running]
  ✓  Canvas & Grid      3/3  A
  ▶  Piece Definitions  1/3
       ▶  Define I and O pieces as 4-cell arrays…
       ○  Define S, Z, T, L, J pieces…
       ○  Render a preview of each piece…
  ○  Movement & Rotation  0/3
  ○  Scoring  0/3

Run /ferment progress for the full phase/step navigator with grades and available actions.

Context budget

The dashboard tracks assistant turns in the current session:

At 50+ turns, model quality tends to degrade. Use /compact to summarise the session before continuing, or finish the current phase and let the next session start fresh.

Stuck-loop protection

If the agent attempts to start the same step three or more times without completing it, the harness blocks further starts and surfaces a recovery prompt:

⚠ Stuck loop detected: step 2 "Implement collision detection" has been started
  3 times without completing. Should we retry with a revised approach, skip
  this step, or pause the ferment?

The block stays active until the step is completed or skipped.

When to use Ferment

Related resources