@mind-fold/open-flow 0.2.15 → 0.2.17

package/README.md

@@ -1,183 +1,106 @@
 # open-flow
 
-AI-assisted development workflow initializer for Cursor, Claude Code and more.
+AI-assisted development workflow system for Cursor, Claude Code and more.
 
-Based on Anthropic's [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/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
+Give your AI coding assistant "long-term memory" through structured progress tracking and project-specific guidelines.
 
-### Prerequisites
-
-- Node.js >= 18.0.0
+Based on Anthropic's [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
 
-### Install
+## Install
 
 ```bash
-npm install -g open-flow
+npm install -g @mind-fold/open-flow
 ```
 
-### Initialize in your project
+## Initialize
 
 ```bash
-cd my-project
-open-flow init
+cd your-project
+
+# Initialize workflow system
+of init
+# or: open-flow init
+
+# Set your developer identity (use your git name)
+of init -u your-git-name
+# or: open-flow init -u your-git-name
 ```
 
 You'll be prompted to select AI tools to configure:
 - Cursor
 - Claude Code
 
-### What gets created
+## Learn the Workflow
 
-```
-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
+After initialization, open your AI IDE (Cursor or Claude Code) and run:
 
-| 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
-
-```bash
-./workflow/scripts/init-developer.sh <your-name>
+```
+/onboard-developer
 ```
 
-### 2. Start AI Session
-
-Use `/init-agent` command in your AI tool.
-
-### 3. Development
-
-1. AI reads guidelines from `workflow/structure/`
-2. AI writes code following the guidelines
-3. Human reviews and tests
-4. Human commits the code
-5. 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:
-1. Reads the lightweight `index.md` (navigation table with section IDs)
-2. Finds relevant section ID for the task
-3. Extracts only the needed section: `sed -n '/@@@section:ID/,/@@@\/section:ID/p' doc.md`
+The AI will explain in detail:
+- **Core Philosophy**: Why this workflow exists, what problems it solves
+- **System Structure**: What each directory does
+- **Command Deep Dive**: Each command's purpose, mechanism, and importance
+- **Real-World Examples**: 5 complete workflow scenarios with step-by-step explanations
 
-Section markers (`@@@section:id`) ensure references don't break when content is added or removed.
+## Quick Reference
 
-This saves tokens and improves focus.
+### Core Workflow Commands
 
-### Multi-Developer Progress Tracking
+| Command | When to Use |
+|---------|-------------|
+| `/init-agent` | Start of every session |
+| `/before-frontend-dev` | Before writing frontend code |
+| `/before-backend-dev` | Before writing backend code |
+| `/check-frontend` | After writing frontend code |
+| `/check-backend` | After writing backend code |
+| `/check-cross-layer` | After changes spanning multiple layers |
+| `/finish-work` | Before human commits |
+| `/record-agent-flow` | After human commits |
+| `/break-loop` | End debugging/investigation |
 
-```
-workflow/agent-progress/
-├── index.md              # Main index
-└── {developer}/          # Per-developer directory
-    ├── index.md          # Personal index
-    └── progress-N.md     # Progress files (max 2000 lines each)
-```
+### Customization Commands
 
-Each developer has independent progress files that don't conflict during collaboration.
+| Command | Purpose |
+|---------|---------|
+| `/generate-frontend-structure` | Auto-scan project and generate frontend guidelines |
+| `/generate-backend-structure` | Auto-scan project and generate backend guidelines |
+| `/extract-to-rules` | Extract knowledge from docs into guidelines |
 
-### Human-in-the-Loop
+### Utility Commands
 
-AI should NOT execute `git commit`. The workflow is:
-1. AI writes code
-2. Human tests locally
-3. Human reviews code
-4. Human commits
-5. AI records progress with commit hash
+| Command | Purpose |
+|---------|---------|
+| `/onboard-developer` | Learn the complete workflow system |
+| `/create-command` | Create new slash command |
+| `/record-question` | Document solved problems |
 
-## Commands
+## CLI Commands
 
 ```bash
-open-flow init        # Initialize in current project
-open-flow update      # Update configuration (coming soon)
-open-flow --version   # Show version
-open-flow --help      # Show help
-```
+of init              # Initialize in current project
+of init -u <name>    # Initialize with developer identity
+of --version         # Show version
+of --help            # Show help
 
-## Comparison with OpenSpec
+# 'open-flow' works the same as 'of'
+open-flow init
+open-flow init -u <name>
+```
 
-| 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 |
+## Key Principles
 
-Both can be used together - OpenSpec for specs, open-flow for workflow.
+1. **AI Never Commits** - AI prepares code, human tests and commits
+2. **Guidelines Before Code** - Read project conventions before writing
+3. **Check After Code** - Verify against guidelines before commit
+4. **Record Everything** - Persist session context for future sessions
 
 ## Contributing
 
 ```bash
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Development
 npm run dev
 ```
 

package/dist/templates/commands/onboard-developer.txt

@@ -4,7 +4,7 @@ YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlyi
 
 ## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
 
-This onboarding has TWO equally important parts:
+This onboarding has THREE equally important parts:
 
 **PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE)
 - Explain WHY this workflow exists
@@ -17,9 +17,18 @@ This onboarding has TWO equally important parts:
   - WHAT HAPPENS: What the command actually does
   - IF SKIPPED: What goes wrong without it
 
-DO NOT skip Part 2. The examples are NOT optional - they are the most important part for understanding how the workflow works in practice. A developer cannot truly understand the system without seeing real workflow examples.
+**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES)
+- Check if project guidelines are still default templates
+- If default, guide the developer to customize them
+- Show feature.json structure for systematic customization
+- Explain the customization workflow
 
-After completing BOTH parts, ask the developer about their first task.
+DO NOT skip any part. All three parts are essential:
+- Part 1 teaches the concepts
+- Part 2 shows how concepts work in practice
+- Part 3 ensures the project has proper guidelines for AI to follow
+
+After completing ALL THREE parts, ask the developer about their first task.
 
 ---
 
@@ -72,6 +81,56 @@ workflow/
 \-- scripts/                # Automation tools
 ```
 
+### Understanding structure/ subdirectories
+
+**frontend/** - Single-layer frontend knowledge:
+- Component patterns (how to write components in THIS project)
+- State management rules (Redux? Zustand? Context?)
+- Styling conventions (CSS modules? Tailwind? Styled-components?)
+- Hook patterns (custom hooks, data fetching)
+
+**backend/** - Single-layer backend knowledge:
+- API design patterns (REST? GraphQL? tRPC?)
+- Database conventions (query patterns, migrations)
+- Error handling standards
+- Logging and monitoring rules
+
+**flows/** - Cross-layer integration knowledge:
+
+This is the CRITICAL directory that many developers overlook. It answers questions that NEITHER frontend nor backend docs can answer alone:
+
+**WHY flows/ EXISTS**:
+When a feature spans multiple layers (frontend + backend + database), there are integration concerns that don't belong in either layer's docs:
+- How does data flow from UI click to database write and back?
+- What's the contract between frontend and backend for this feature?
+- What happens when one layer changes - what must the other layer update?
+- How do we handle cross-layer error propagation?
+- What's the deployment order when both layers change?
+
+**WHAT flows/ CONTAINS**:
+1. **Feature flow documentation**: End-to-end data flow for complex features
+2. **API contracts**: Shared type definitions, request/response schemas
+3. **Cross-layer checklists**: "When changing X, also check Y"
+4. **Integration patterns**: How layers communicate in this project
+5. **Deployment guides**: Order of operations for multi-layer changes
+
+**WHEN TO READ flows/**:
+- Before implementing ANY feature that touches both frontend and backend
+- When debugging issues that might be integration-related
+- Before making API changes
+- When planning new features
+
+**EXAMPLE**:
+A "user authentication" flow doc might include:
+- Frontend: What happens when user clicks login
+- API: What endpoint is called, what's the request/response format
+- Backend: How credentials are validated, session created
+- Database: What gets stored, what gets returned
+- Error cases: How each layer handles auth failures
+- Security: Token handling, refresh logic
+
+Without flows/ documentation, AI treats frontend and backend as isolated islands. With flows/, AI understands how the layers work TOGETHER.
+
 ---
 
 ## COMMAND DEEP DIVE
@@ -158,6 +217,71 @@ This causes "context drift" - AI starts following guidelines but gradually rever
 
 ---
 
+### /check-cross-layer - Multi-Dimension Verification
+
+**WHY IT EXISTS**:
+`/check-frontend` and `/check-backend` verify code within a single layer. But most bugs don't come from lack of technical skill - they come from "didn't think of it":
+- Changed a constant in one place, missed 5 other places using it
+- Modified database schema, forgot to update the API layer
+- Created a new utility function, but similar one already exists
+- Fixed a bug in one component, but 3 other components have the same bug
+
+**THE CORE INSIGHT**:
+Real-world changes have multiple "dimensions" that need checking:
+1. **Cross-layer data flow**: Does data flow correctly from UI -> API -> Service -> Database and back?
+2. **Code reuse**: Are there duplicate definitions? Should this be a shared constant?
+3. **Consistency**: Is the same concept displayed the same way in different places?
+4. **Impact scope**: Did you check ALL files affected by this change?
+
+**WHAT IT ACTUALLY DOES**:
+1. Identifies which dimensions your change involves
+2. For each dimension, runs targeted checks:
+
+**Dimension A - Cross-Layer Data Flow** (when changes touch 3+ layers):
+- Trace read flow: Database -> Service -> API -> Hook -> Component
+- Trace write flow: Component -> Hook -> API -> Service -> Database
+- Check types passed correctly between layers
+- Check errors propagated to UI
+- Check loading states at each layer
+
+**Dimension B - Code Reuse** (when modifying constants/config):
+- Search: How many places define this value?
+- If 2+ places -> Should extract to shared constant
+- After modification, all usage sites updated?
+
+**Dimension B2 - New Utilities** (when creating helper functions):
+- Search for existing similar utilities first
+- If similar exists, extend instead of duplicate
+- If new, is it in the right location?
+
+**Dimension B3 - Batch Modifications** (after fixing multiple files):
+- Did you check ALL files with similar patterns?
+- Any files missed?
+- Should this pattern be abstracted?
+
+**Dimension C - Import Paths** (when creating new files):
+- Using correct path aliases?
+- No circular imports?
+- Consistent with project convention?
+
+**Dimension D - Same-Layer Consistency** (when modifying display logic):
+- Search for other components using same concept
+- Are displays consistent?
+- Should they share configuration?
+
+**WHY THIS MATTERS**:
+- Without check-cross-layer: You fix one bug, but miss 5 related places. You create a utility that already exists. You change a constant but miss half the usages.
+- With check-cross-layer: Systematic verification across all dimensions. No "didn't think of it" bugs.
+
+**ANALOGY**: Like a pre-flight checklist for pilots. Not because pilots don't know how to fly, but because complex systems have many dimensions that are easy to overlook.
+
+**RELATED DOCUMENTS** (referenced by this command):
+- `workflow/structure/flows/pre-implementation-checklist.md` - Questions BEFORE coding
+- `workflow/structure/flows/code-reuse-thinking-guide.md` - Pattern recognition
+- `workflow/structure/flows/cross-layer-thinking-guide.md` - Data flow analysis
+
+---
+
 ### /finish-work - Holistic Pre-Commit Review
 
 **WHY IT EXISTS**:
@@ -418,8 +542,211 @@ Debugging and investigation can spiral - AI keeps trying things without concludi
 
 ---
 
-After explaining, ask the developer:
-1. What kind of work will they be doing? (frontend/backend/full-stack)
-2. Do they have a specific task to start with?
+# PART 3: Customize Your Development Guidelines
+
+After explaining Part 1 and Part 2, check if the project's development guidelines need customization.
+
+## Step 1: Check Current Guidelines Status
+
+Check if `workflow/structure/` contains default templates or customized guidelines:
+
+```bash
+# Check if files are still templates (look for placeholder text)
+grep -l "TODO" workflow/structure/backend/*.md 2>/dev/null | head -5
+grep -l "your project" workflow/structure/frontend/*.md 2>/dev/null | head -5
+
+# Also check the project's actual tech stack
+cat package.json 2>/dev/null | head -30
+ls -la src/ 2>/dev/null || ls -la apps/ 2>/dev/null
+```
+
+## Step 2: Explain Guidelines Status (Adjust Tone Based on Situation)
+
+**Situation A: First time using open-flow in this project**
+
+If this appears to be a new open-flow setup (guidelines are default templates), explain warmly:
+
+"I see that the development guidelines in `workflow/structure/` are still the default templates that come with open-flow. This is completely normal if you've just set up the workflow system!
+
+The default templates use generic examples (React, TypeScript, Drizzle ORM, etc.) that may not match your actual tech stack. To make `/before-*-dev` commands truly useful, you'll want to customize these guidelines with YOUR project's patterns.
+
+This is a great opportunity - let's set up a task to customize your guidelines. I'll show you how to use **feature.json** for complex tasks like this."
+
+**Situation B: Existing open-flow setup, new team member**
+
+If guidelines appear customized (project-specific examples found), explain:
+
+"Great news! Your team has already customized the development guidelines. You can start using `/before-*-dev` commands right away to learn your project's conventions.
+
+I recommend reading through `workflow/structure/` to familiarize yourself with the team's coding standards."
+
+## Step 3: Create Feature for Guidelines Customization (If Needed)
+
+If guidelines need customization, DO THIS IN THE CURRENT SESSION:
+
+**First, explain the concept of feature.json**:
+
+"For complex tasks with multiple subtasks, we use **feature.json** to track progress. This is important because:
+- Complex tasks often span multiple AI sessions
+- Each session has limited context
+- feature.json persists the task breakdown across sessions
+- Future sessions can read feature.json to continue where you left off
+
+Let me create one for you now, and this will also teach you how to create feature.json for your own complex tasks in the future."
+
+**Then create the feature**:
+
+```bash
+./workflow/scripts/feature.sh create customize-guidelines
+```
+
+**Now fill in the feature.json based on the project's actual tech stack**:
+
+Analyze the project's tech stack and create appropriate subtasks. Example for a typical project:
+
+```json
+{
+  "name": "customize-guidelines",
+  "description": "Customize development guidelines to match this project's actual tech stack and patterns",
+  "created": "[current-date]",
+  "status": "in-progress",
+  "subtasks": [
+    {
+      "id": "analyze-tech-stack",
+      "title": "Analyze Project Tech Stack",
+      "description": "Identify frameworks, libraries, and patterns used in this project",
+      "status": "completed",
+      "notes": "Analyzed in onboard session: [list findings]"
+    },
+    {
+      "id": "backend-database",
+      "title": "Backend: Database Guidelines",
+      "description": "Analyze database patterns and rewrite workflow/structure/backend/database-guidelines.md",
+      "status": "pending"
+    },
+    {
+      "id": "backend-directory",
+      "title": "Backend: Directory Structure",
+      "description": "Document backend directory organization in workflow/structure/backend/directory-structure.md",
+      "status": "pending"
+    },
+    {
+      "id": "backend-error-handling",
+      "title": "Backend: Error Handling",
+      "description": "Document error handling patterns in workflow/structure/backend/error-handling.md",
+      "status": "pending"
+    },
+    {
+      "id": "frontend-components",
+      "title": "Frontend: Component Guidelines",
+      "description": "Analyze component patterns and rewrite workflow/structure/frontend/component-guidelines.md",
+      "status": "pending"
+    },
+    {
+      "id": "frontend-state",
+      "title": "Frontend: State Management",
+      "description": "Document state management approach in workflow/structure/frontend/state-management.md",
+      "status": "pending"
+    },
+    {
+      "id": "frontend-directory",
+      "title": "Frontend: Directory Structure",
+      "description": "Document frontend directory organization in workflow/structure/frontend/directory-structure.md",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+**Adapt subtasks based on actual tech stack**:
+- If no database -> remove database subtask
+- If no React -> change component guidelines to vanilla JS patterns
+- If Rust backend -> change to Rust-specific guidelines
+- Add project-specific subtasks as needed
+
+## Step 4: Teach User How to Use Feature.json for Future Tasks
+
+Explain to the developer:
+
+"Now you've seen how feature.json works. In the future, when you have complex tasks, you can create your own feature.json by telling AI:
+
+**How to ask AI to create a feature.json**:
+
+> 'I need to [describe complex task]. This seems like a multi-session task. Can you help me:
+> 1. Create a feature with `./workflow/scripts/feature.sh create [feature-name]`
+> 2. Break it down into subtasks in feature.json
+> 3. Mark the first subtask as in-progress'
+
+**When to use feature.json**:
+- Task has 3+ distinct steps
+- Task might span multiple sessions
+- Task has dependencies between steps
+- You want to track progress systematically
+
+**Feature.json lifecycle**:
+1. Create feature -> feature.json created with subtasks
+2. Work on subtasks -> update status in feature.json
+3. Human commits -> git commit the changes
+4. Record session -> /record-agent-flow captures progress
+5. New session -> AI reads feature.json, continues from where you left off
+6. Complete all subtasks -> archive feature"
+
+## Step 5: Complete This Session
+
+Guide the developer to complete the onboard session properly:
+
+"Let's wrap up this onboard session:
+
+1. **Review the feature.json** I created - does it capture the right subtasks for your project?
+
+2. **Commit the feature.json**:
+   ```bash
+   git add workflow/features/customize-guidelines/feature.json
+   git commit -m 'feat(workflow): add customize-guidelines feature'
+   ```
+
+3. **Record this session**:
+   Use `/record-agent-flow` to record what we did in this onboard session.
+
+4. **Start customization in a new session**:
+   - Open a new conversation window
+   - Run `/init-agent` - AI will see the customize-guidelines feature
+   - AI will read feature.json and ask which subtask to work on
+   - Work through subtasks one by one"
+
+## Step 6: Show Example of Continuing in Next Session
+
+"In your next session, after `/init-agent`, you can say:
+
+> 'I want to continue the customize-guidelines feature. Let's work on the backend-database subtask. Please:
+> 1. Analyze my project's database code
+> 2. Identify the ORM, query patterns, transaction handling
+> 3. Rewrite workflow/structure/backend/database-guidelines.md with examples from MY codebase'
+
+The AI will read the feature.json, understand the context, and help you complete that subtask."
+
+## Customization Commands Reference
+
+These commands can help with guidelines customization:
+
+| Command | Purpose |
+|---------|---------|
+| `/generate-frontend-structure` | Auto-scan project and generate frontend guidelines |
+| `/generate-backend-structure` | Auto-scan project and generate backend guidelines |
+| `/extract-to-rules` | Extract knowledge from a document into guidelines |
+
+---
+
+After completing all three parts, summarize and ask:
+
+"You're now onboarded to the workflow system! Here's what we covered:
+- Part 1: Core concepts (why this workflow exists)
+- Part 2: Real-world examples (how to apply the workflow)
+- Part 3: Guidelines customization (created feature.json if needed)
+
+**Next steps**:
+1. Commit the feature.json (if created)
+2. Use `/record-agent-flow` to record this session
+3. Start a new session to begin customizing guidelines (or your actual development work)
 
-Then guide them through their first task using the appropriate workflow.
+What would you like to do first?"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mind-fold/open-flow",
-	"version": "0.2.15",
+	"version": "0.2.17",
 	"description": "AI-assisted development workflow initializer for Cursor, Claude Code and more",
 	"type": "module",
 	"main": "./dist/index.js",