@mind-fold/open-flow

open-flow

AI-assisted development workflow initializer for Cursor, Claude Code and more.

Based on Anthropic's Effective Harnesses for Long-Running Agents.

Why open-flow?

AI coding assistants are powerful but lack continuity across sessions. open-flow adds a lightweight workflow system that gives AI "long-term memory" through structured documentation.

Key outcomes:

• Multi-developer support: Each developer (human or AI) has independent progress tracking
• Guidelines index system: index.md + doc.md two-layer structure for efficient knowledge access
• Short commands: Pre-defined prompts for common operations
• Human-in-the-loop: AI writes code, human reviews and commits

Getting Started

Prerequisites

• Node.js >= 18.0.0

Install

npm install -g open-flow

Initialize in your project

cd my-project
open-flow init

You'll be prompted to select AI tools to configure:

• Cursor
• Claude Code

What gets created

your-project/
├── .cursor/commands/          # Cursor short commands
│   ├── init-agent.md
│   ├── check-frontend.md
│   ├── check-backend.md
│   ├── record-agent-flow.md
│   └── onboard-developer.md
├── .claude/commands/          # Claude Code short commands
├── workflow/
│   ├── scripts/
│   │   ├── init-developer.sh
│   │   └── get-developer.sh
│   ├── agent-progress/
│   │   └── index.md
│   ├── structure/
│   │   ├── frontend/
│   │   │   ├── index.md
│   │   │   └── doc.md
│   │   └── backend/
│   │       ├── index.md
│   │       └── doc.md
│   ├── feature.json
│   └── flow.md
├── init-agent.md
└── AGENTS.md

Short Commands

Command	Purpose
/init-agent	Initialize AI session, read context and guidelines
/before-frontend-dev	Read frontend guidelines before starting development
/before-backend-dev	Read backend guidelines before starting development
/check-frontend	Check frontend code against guidelines
/check-backend	Check backend code against guidelines
/record-agent-flow	Record work progress (after human commits)
/record-question	Document a solved problem for future reference
/onboard-developer	Guide new developer through setup
/update-frontend-structure	Update frontend guidelines if new patterns found
/update-backend-structure	Update backend guidelines if new patterns found
/create-command	Create a new slash command in both .cursor/ and .claude/ directories

Workflow

1. Initialize Developer Identity

./workflow/scripts/init-developer.sh <your-name>

2. Start AI Session

Use /init-agent command in your AI tool.

3. Development

• AI reads guidelines from workflow/structure/
• AI writes code following the guidelines
• Human reviews and tests
• Human commits the code
• Use /record-agent-flow to record progress

4. Customize Guidelines

Fill in your project-specific guidelines in:

• workflow/structure/frontend/doc.md
• workflow/structure/backend/doc.md

Requirements:

• Write all documentation in English
• Add section markers: @@@section:kebab-case-id and @@@/section:kebab-case-id
• Update index.md files with section IDs for quick navigation

Key Concepts

index.md + doc.md Structure

Instead of reading entire guideline documents (which can be 1000+ lines), AI:

• Reads the lightweight index.md (navigation table with section IDs)
• Finds relevant section ID for the task
• Extracts only the needed section: sed -n '/@@@section:ID/,/@@@\/section:ID/p' doc.md

Section markers (@@@section:id) ensure references don't break when content is added or removed.

This saves tokens and improves focus.

Multi-Developer Progress Tracking

workflow/agent-progress/
├── index.md              # Main index
└── {developer}/          # Per-developer directory
    ├── index.md          # Personal index
    └── progress-N.md     # Progress files (max 2000 lines each)

Each developer has independent progress files that don't conflict during collaboration.

Human-in-the-Loop

AI should NOT execute git commit. The workflow is:

• AI writes code
• Human tests locally
• Human reviews code
• Human commits
• AI records progress with commit hash

Commands

open-flow init        # Initialize in current project
open-flow update      # Update configuration (coming soon)
open-flow --version   # Show version
open-flow --help      # Show help

Comparison with OpenSpec

Aspect	OpenSpec	open-flow
Focus	Spec-driven development	Memory-driven workflow
Main feature	Change proposals & specs	Progress tracking & guidelines
Collaboration	Single change flow	Multi-developer directories
Guidelines	N/A	index.md + doc.md system

Both can be used together - OpenSpec for specs, open-flow for workflow.

Contributing

# Install dependencies
npm install

# Build
npm run build

# Development
npm run dev

License

MIT