_                      __ _
  __| | ___  ___ _ __      / _| | _____      __
 / _` |/ _ \/ _ \ '_ \    | |_| |/ _ \ \ /\ / /
| (_| |  __/  __/ |_) |   |  _| | (_) \ V  V /
 \__,_|\___|\___| .__/    |_| |_|\___/ \_/\_/
               |_|

Philosophy

• Stay in flow — Minimize context switches, maximize deep work
• Conversational ideation with proactive gap discovery
• Specs define intent, tasks close reality gaps
• Parallel execution with context-aware checkpointing
• Atomic commits for clean rollback

Quick Start

# Install (or update)
npx deepflow

# Uninstall
npx deepflow --uninstall

# In your project
claude

# 1. Discuss what you want to build
# 2. Generate spec when ready
/df:spec image-upload

# 3. Compare specs to code, generate tasks
/df:plan

# 4. Execute tasks with parallel agents
/df:execute

# 5. Verify specs are satisfied
/df:verify

The Flow

CONVERSATION
    │ Describe what you want
    │ LLM asks gap questions
    ▼
/df:spec <name>
    │ Creates specs/{name}.md
    ▼
/df:plan
    │ Detects project context/patterns
    │ Analyzes specs vs codebase
    │ Creates PLAN.md with tasks
    │ Renames: feature.md → doing-feature.md
    ▼
/df:execute
    │ Follows existing patterns
    │ Parallel agents, file conflicts serialize
    │ Context-aware (≥50% → checkpoint)
    │ Atomic commit per task
    ▼
/df:verify
    │ Checks requirements met
    │ Renames: doing-feature.md → done-feature.md

Spec Lifecycle

specs/
  feature.md        → new, needs /df:plan
  doing-feature.md  → in progress, has tasks in PLAN.md
  done-feature.md   → completed, history embedded

Works With Any Project

Greenfield: Everything is new, agents create from scratch.

Ongoing: Detects existing patterns, follows conventions, integrates with current code.

Context-Aware Execution

Statusline shows context usage. At ≥50%:

• Waits for running agents
• Checkpoints state
• Resume with /df:execute --continue

Commands

| Command | Purpose | |---------|---------| | /df:spec <name> | Generate spec from conversation | | /df:plan | Compare specs to code, create tasks | | /df:execute | Run tasks with parallel agents | | /df:verify | Check specs satisfied | | /df:update | Update deepflow to latest |

File Structure

your-project/
├── specs/
│   ├── auth.md           # new spec
│   ├── doing-upload.md   # in progress
│   └── done-payments.md  # completed
├── PLAN.md               # active tasks only
└── .deepflow/
    ├── context.json      # context % for execution
    ├── checkpoint.json   # resume state
    └── results/          # agent results

Configuration

Create .deepflow/config.yaml:

project:
  source_dir: src/
  specs_dir: specs/

Principles

1. Stay in flow — Uninterrupted deep work
2. Confirm before assume — Search code before marking "missing"
3. Complete implementations — No stubs, no placeholders
4. Atomic commits — One task = one commit
5. Context-aware — Checkpoint before limits

License

MIT