@mind-fold/open-flow 0.1.5 → 0.1.6

package/dist/configurators/workflow.js

@@ -1,15 +1,14 @@
-import fs from 'node:fs';
-import path from 'node:path';
+import fs from "node:fs";
+import path from "node:path";
 export async function createWorkflowStructure(cwd) {
-    const workflowDir = path.join(cwd, 'workflow');
     // Create directories
     const dirs = [
-        'workflow',
-        'workflow/scripts',
-        'workflow/agent-progress',
-        'workflow/structure',
-        'workflow/structure/frontend',
-        'workflow/structure/backend',
+        "workflow",
+        "workflow/scripts",
+        "workflow/agent-progress",
+        "workflow/structure",
+        "workflow/structure/frontend",
+        "workflow/structure/backend",
     ];
     for (const dir of dirs) {
         fs.mkdirSync(path.join(cwd, dir), { recursive: true });
@@ -24,6 +23,8 @@ export async function createWorkflowStructure(cwd) {
     await createFeatureJson(cwd);
     // Create flow.md
     await createFlowMd(cwd);
+    // Create onboarding-guide.md
+    await createOnboardingGuide(cwd);
     // Create .gitignore for workflow
     await createWorkflowGitignore(cwd);
 }
@@ -146,11 +147,274 @@ fi
 
 cat "$DEVELOPER_FILE" | grep "name:" | cut -d' ' -f2
 `;
-    fs.writeFileSync(path.join(cwd, 'workflow/scripts/init-developer.sh'), initDeveloperScript);
-    fs.writeFileSync(path.join(cwd, 'workflow/scripts/get-developer.sh'), getDeveloperScript);
+    fs.writeFileSync(path.join(cwd, "workflow/scripts/init-developer.sh"), initDeveloperScript);
+    fs.writeFileSync(path.join(cwd, "workflow/scripts/get-developer.sh"), getDeveloperScript);
     // Make scripts executable
-    fs.chmodSync(path.join(cwd, 'workflow/scripts/init-developer.sh'), '755');
-    fs.chmodSync(path.join(cwd, 'workflow/scripts/get-developer.sh'), '755');
+    fs.chmodSync(path.join(cwd, "workflow/scripts/init-developer.sh"), "755");
+    fs.chmodSync(path.join(cwd, "workflow/scripts/get-developer.sh"), "755");
+    // Create extract-md-headings.sh script
+    const extractMdHeadingsScript = `#!/bin/zsh
+
+# ============================================
+# Markdown Heading Line Number Extraction Tool
+# ============================================
+#
+# Purpose: Auto-extract headings and line numbers from markdown files
+# Used to quickly update line number references in index.md
+#
+# Usage:
+#   ./extract-md-headings.sh <markdown-file> [options]
+#
+# Options:
+#   -l, --level <1-6>    Only extract specific heading levels (default: 1,2)
+#   -f, --format <type>  Output format: table(default), list, csv, json
+#   -r, --range          Show line number ranges (current heading to next)
+#   -h, --help           Show help
+#
+# Examples:
+#   # Extract all # and ## level headings
+#   ./extract-md-headings.sh doc.md
+#
+#   # Only extract ## level headings
+#   ./extract-md-headings.sh doc.md -l 2
+#
+#   # Output as CSV format
+#   ./extract-md-headings.sh doc.md -f csv
+#
+#   # Show line number ranges
+#   ./extract-md-headings.sh doc.md -r
+#
+# ============================================
+
+# Color definitions
+RED='\\033[0;31m'
+GREEN='\\033[0;32m'
+YELLOW='\\033[1;33m'
+BLUE='\\033[0;34m'
+CYAN='\\033[0;36m'
+NC='\\033[0m' # No Color
+
+# Default parameters
+LEVELS="1,2"
+FORMAT="table"
+SHOW_RANGE=false
+
+# Show help
+show_help() {
+    echo "📚 Markdown Heading Line Number Extraction Tool"
+    echo ""
+    echo "Purpose: Auto-extract headings and line numbers from markdown files"
+    echo ""
+    echo "Usage:"
+    echo "  $0 <markdown-file> [options]"
+    echo ""
+    echo "Options:"
+    echo "  -l, --level <1-6>    Only extract specific heading levels (default: 1,2)"
+    echo "                       Can be single number or comma-separated list: 1,2,3"
+    echo "  -f, --format <type>  Output format:"
+    echo "                       - table  Table format (default)"
+    echo "                       - list   List format"
+    echo "                       - csv    CSV format"
+    echo "                       - json   JSON format"
+    echo "  -r, --range          Show line number ranges (current to next same/higher level)"
+    echo "  -h, --help           Show this help"
+    echo ""
+    echo "Examples:"
+    echo "  # Extract all # and ## level headings"
+    echo "  $0 doc.md"
+    echo ""
+    echo "  # Only extract ## level headings"
+    echo "  $0 doc.md -l 2"
+    echo ""
+    echo "  # Extract # ## ### three levels"
+    echo "  $0 doc.md -l 1,2,3"
+    echo ""
+    echo "  # Output as CSV format"
+    echo "  $0 doc.md -f csv"
+    echo ""
+    echo "  # Show line number ranges (for Read tool)"
+    echo "  $0 doc.md -r"
+    echo ""
+    exit 0
+}
+
+# Parse command line arguments
+POSITIONAL_ARGS=()
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -l|--level)
+            LEVELS="$2"
+            shift 2
+            ;;
+        -f|--format)
+            FORMAT="$2"
+            shift 2
+            ;;
+        -r|--range)
+            SHOW_RANGE=true
+            shift
+            ;;
+        -h|--help)
+            show_help
+            ;;
+        *)
+            POSITIONAL_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Restore positional args
+set -- "\${POSITIONAL_ARGS[@]}"
+
+# Check file argument
+if [[ $# -eq 0 ]]; then
+    echo -e "\${RED}Error: Please provide markdown file path\${NC}"
+    echo "Use -h or --help to see help"
+    exit 1
+fi
+
+MD_FILE="$1"
+
+# Check if file exists
+if [[ ! -f "$MD_FILE" ]]; then
+    echo -e "\${RED}Error: File not found: $MD_FILE\${NC}"
+    exit 1
+fi
+
+# Check if file is markdown
+if [[ ! "$MD_FILE" =~ \\.(md|markdown)$ ]]; then
+    echo -e "\${YELLOW}Warning: File may not be markdown format: $MD_FILE\${NC}"
+fi
+
+# Build awk script to extract headings
+AWK_SCRIPT='
+BEGIN {
+    split(levels, level_array, ",")
+    for (i in level_array) {
+        allowed_levels[level_array[i]] = 1
+    }
+}
+/^#{1,6} / {
+    # Calculate heading level
+    match($0, /^#+/)
+    level = RLENGTH
+
+    # Check if this is a level we want
+    if (level in allowed_levels) {
+        # Extract heading text (remove leading # and space)
+        title = substr($0, level + 2)
+        # Remove trailing # symbols (some markdown styles)
+        gsub(/ #+$/, "", title)
+
+        # Save heading info (use @@@ as delimiter)
+        headings[++count] = level "@@@" NR "@@@" title
+    }
+}
+END {
+    for (i = 1; i <= count; i++) {
+        split(headings[i], parts, "@@@")
+        level = parts[1]
+        line = parts[2]
+        title = parts[3]
+
+        # Calculate end line (previous line of next same/higher level heading)
+        end_line = total_lines
+        for (j = i + 1; j <= count; j++) {
+            split(headings[j], next_parts, "@@@")
+            next_level = next_parts[1]
+            next_line = next_parts[2]
+            if (next_level <= level) {
+                end_line = next_line - 1
+                break
+            }
+        }
+
+        printf "%d|%d|%d|%s\\n", level, line, end_line, title
+    }
+}
+'
+
+# Get total lines
+TOTAL_LINES=$(wc -l < "$MD_FILE" | tr -d ' ')
+
+# Extract headings
+HEADINGS=$(awk -v levels="$LEVELS" -v total_lines="$TOTAL_LINES" "$AWK_SCRIPT" "$MD_FILE")
+
+# Check if headings found
+if [[ -z "$HEADINGS" ]]; then
+    echo -e "\${YELLOW}No matching headings found\${NC}"
+    exit 0
+fi
+
+# Output based on format
+case $FORMAT in
+    table)
+        echo -e "\${GREEN}📋 Heading List\${NC}"
+        echo -e "\${CYAN}File: $MD_FILE\${NC}"
+        echo ""
+        printf "%-8s %-12s %-12s %s\\n" "Level" "Line" "Range" "Title"
+        printf "%-8s %-12s %-12s %s\\n" "----" "----" "----" "----"
+        echo "$HEADINGS" | while IFS='|' read -r level line end_line title; do
+            indent=$(printf '%*s' $((level * 2)) '')
+            if [[ "$SHOW_RANGE" == true ]]; then
+                range="L\${line}-\${end_line}"
+            else
+                range="L\${line}"
+            fi
+            printf "%-8s %-12s %-12s %s%s\\n" "$level" "$line" "$range" "$indent" "$title"
+        done
+        ;;
+
+    list)
+        echo -e "\${GREEN}📋 Heading List\${NC}"
+        echo -e "\${CYAN}File: $MD_FILE\${NC}"
+        echo ""
+        echo "$HEADINGS" | while IFS='|' read -r level line end_line title; do
+            indent=$(printf '%*s' $((level * 2)) '')
+            if [[ "$SHOW_RANGE" == true ]]; then
+                echo "L\${line}-\${end_line}: \${indent}$title"
+            else
+                echo "L\${line}: \${indent}$title"
+            fi
+        done
+        ;;
+
+    csv)
+        echo "Level,LineStart,LineEnd,Title"
+        echo "$HEADINGS" | while IFS='|' read -r level line end_line title; do
+            # CSV needs to escape commas and quotes in title
+            escaped_title=$(echo "$title" | sed 's/"/""/g')
+            echo "$level,$line,$end_line,\\"$escaped_title\\""
+        done
+        ;;
+
+    json)
+        echo "["
+        first=true
+        echo "$HEADINGS" | while IFS='|' read -r level line end_line title; do
+            if [[ "$first" != true ]]; then
+                echo ","
+            fi
+            first=false
+            # JSON needs to escape quotes and backslashes
+            escaped_title=$(echo "$title" | sed 's/\\\\/\\\\\\\\/g' | sed 's/"/\\\\"/g')
+            printf '  {"level": %d, "lineStart": %d, "lineEnd": %d, "title": "%s"}' \\
+                   "$level" "$line" "$end_line" "$escaped_title"
+        done
+        echo ""
+        echo "]"
+        ;;
+
+    *)
+        echo -e "\${RED}Error: Unknown output format: $FORMAT\${NC}"
+        echo "Supported formats: table, list, csv, json"
+        exit 1
+        ;;
+esac
+`;
+    fs.writeFileSync(path.join(cwd, "workflow/scripts/extract-md-headings.sh"), extractMdHeadingsScript);
+    fs.chmodSync(path.join(cwd, "workflow/scripts/extract-md-headings.sh"), "755");
 }
 async function createAgentProgressIndex(cwd) {
     const content = `# Agent Progress
@@ -215,7 +479,7 @@ One-line description of what was done
 3. **Update personal index** - After each session
 4. **Sequential numbering** - progress-1.md, progress-2.md, etc.
 `;
-    fs.writeFileSync(path.join(cwd, 'workflow/agent-progress/index.md'), content);
+    fs.writeFileSync(path.join(cwd, "workflow/agent-progress/index.md"), content);
 }
 async function createStructureTemplates(cwd) {
     // Frontend index.md
@@ -561,26 +825,26 @@ console.log('User created: ' + user.id);
 
 **Note**: Update line numbers in index.md when you modify this document.
 `;
-    fs.writeFileSync(path.join(cwd, 'workflow/structure/frontend/index.md'), frontendIndex);
-    fs.writeFileSync(path.join(cwd, 'workflow/structure/frontend/doc.md'), frontendDoc);
-    fs.writeFileSync(path.join(cwd, 'workflow/structure/backend/index.md'), backendIndex);
-    fs.writeFileSync(path.join(cwd, 'workflow/structure/backend/doc.md'), backendDoc);
+    fs.writeFileSync(path.join(cwd, "workflow/structure/frontend/index.md"), frontendIndex);
+    fs.writeFileSync(path.join(cwd, "workflow/structure/frontend/doc.md"), frontendDoc);
+    fs.writeFileSync(path.join(cwd, "workflow/structure/backend/index.md"), backendIndex);
+    fs.writeFileSync(path.join(cwd, "workflow/structure/backend/doc.md"), backendDoc);
 }
 async function createFeatureJson(cwd) {
     const content = {
-        project: 'My Project',
-        lastUpdated: new Date().toISOString().split('T')[0],
-        version: '1.0.0',
+        project: "My Project",
+        lastUpdated: new Date().toISOString().split("T")[0],
+        version: "1.0.0",
         categories: {
             example: {
-                name: 'Example Category',
+                name: "Example Category",
                 features: [
                     {
-                        id: 'example-001',
-                        name: 'Example Feature',
-                        description: 'An example feature to demonstrate the structure',
-                        status: 'planned',
-                        priority: 'medium',
+                        id: "example-001",
+                        name: "Example Feature",
+                        description: "An example feature to demonstrate the structure",
+                        status: "planned",
+                        priority: "medium",
                     },
                 ],
             },
@@ -591,18 +855,18 @@ async function createFeatureJson(cwd) {
             inProgress: 0,
             planned: 1,
             blocked: 0,
-            completionRate: '0%',
+            completionRate: "0%",
         },
         notes: [
-            'Feature ID format: category-XXX (e.g., auth-001, ui-002)',
-            'Status: completed | in-progress | planned | blocked',
-            'Priority: high | medium | low',
-            'When completed, add completedAt (YYYY-MM-DD) and commit (hash)',
-            'When blocked, add blockedReason field',
-            'Update statistics after changing feature status',
+            "Feature ID format: category-XXX (e.g., auth-001, ui-002)",
+            "Status: completed | in-progress | planned | blocked",
+            "Priority: high | medium | low",
+            "When completed, add completedAt (YYYY-MM-DD) and commit (hash)",
+            "When blocked, add blockedReason field",
+            "Update statistics after changing feature status",
         ],
     };
-    fs.writeFileSync(path.join(cwd, 'workflow/feature.json'), JSON.stringify(content, null, 2));
+    fs.writeFileSync(path.join(cwd, "workflow/feature.json"), JSON.stringify(content, null, 2));
 }
 async function createFlowMd(cwd) {
     const content = `# Development Workflow
@@ -611,13 +875,50 @@ async function createFlowMd(cwd) {
 
 ---
 
-## Core Principles
+## Table of Contents
+
+1. [Workflow Overview](#workflow-overview)
+2. [Session Start Process](#session-start-process)
+3. [Development Process](#development-process)
+4. [Session End](#session-end)
+5. [File Descriptions](#file-descriptions)
+6. [Best Practices](#best-practices)
+
+---
+
+## Workflow Overview
+
+### Core Principles
 
 1. **Read Before Write** - Understand context before starting
-2. **Follow Standards** - Read \`workflow/structure/\` guidelines before coding
+2. **Follow Standards** - ⚠️ **MUST read \`workflow/structure/\` guidelines (index → doc) before coding**
 3. **Incremental Development** - Complete one feature at a time
-4. **Record Promptly** - Update tracking files after completion
-5. **Document Limits** - Max 2000 lines per agent-progress document
+4. **Record Promptly** - Update tracking files immediately after completion
+5. **Document Limits** - ⚠️ **Max 2000 lines per agent-progress document**
+
+### File System
+
+\`\`\`
+workflow/
+├── .developer           # Developer identity (gitignored)
+├── scripts/
+│   ├── init-developer.sh    # Initialize developer identity
+│   └── get-developer.sh     # Get current developer name
+├── agent-progress/       # AI Agent work progress records
+│   ├── index.md         # Progress index + Session template
+│   └── {developer}/     # Per-developer directories
+│       ├── index.md     # Personal index
+│       └── progress-N.md  # Progress files (sequential numbering)
+├── structure/           # ⚠️ MUST READ before coding
+│   ├── frontend/
+│   │   ├── index.md    # Frontend guidelines index (read first)
+│   │   └── doc.md      # Frontend guidelines detailed doc (read specific sections)
+│   └── backend/
+│       ├── index.md    # Backend guidelines index (read first)
+│       └── doc.md      # Backend guidelines detailed doc (read specific sections)
+├── feature.json         # Feature tracking list (single file, no limit)
+└── flow.md             # This document
+\`\`\`
 
 ---
 
@@ -625,6 +926,8 @@ async function createFlowMd(cwd) {
 
 ### Step 1: Read Work Context
 
+Read the following files in order to quickly establish context:
+
 \`\`\`bash
 # 0. Check your developer identity
 ./workflow/scripts/get-developer.sh
@@ -636,24 +939,58 @@ cat workflow/agent-progress/$DEVELOPER/index.md
 # 2. Check feature status
 cat workflow/feature.json
 
-# 3. Check Git history
+# 3. Check Git history (use git command directly)
 git status
 git log --oneline -20
 \`\`\`
 
-### Step 2: Read Development Guidelines
+### Step 2: Read Development Guidelines Index ⚠️ REQUIRED
+
+**⚠️ CRITICAL: MUST read guidelines before writing any code**
 
-Based on your task (frontend/backend), read the corresponding guidelines:
+Based on what you'll develop (frontend/backend), read the corresponding guidelines **index document**:
 
+**Frontend Development**:
 \`\`\`bash
-# Frontend
 cat workflow/structure/frontend/index.md
+\`\`\`
+- Find corresponding chapters based on task type (e.g., "New Query Hook", "Write Component")
+- Note down chapter names and line number ranges
+- This is **mandatory**, not optional
 
-# Backend
+**Backend Development**:
+\`\`\`bash
 cat workflow/structure/backend/index.md
 \`\`\`
+- Find corresponding chapters based on scenario (e.g., "New API Module", "Write Batch Tasks")
+- Note down chapter names and line number ranges
+- This is **mandatory**, not optional
+
+### Step 3: Read Specific Guidelines ⚠️ REQUIRED
+
+**⚠️ CRITICAL: Read detailed guidelines for your specific task**
+
+Based on line numbers found in index, read detailed guideline documents:
+
+**Frontend**:
+\`\`\`bash
+# Use Read tool to read specific line ranges
+# Example: L179-264 (Query Hook guidelines)
+Read workflow/structure/frontend/doc.md --offset 179 --limit 85
+\`\`\`
+- **MUST read** the sections relevant to your task
+- Do NOT skip this step
+
+**Backend**:
+\`\`\`bash
+# Use Read tool to read specific line ranges
+# Example: L5-28 (Directory structure guidelines)
+Read workflow/structure/backend/doc.md --offset 5 --limit 23
+\`\`\`
+- **MUST read** the sections relevant to your task
+- Do NOT skip this step
 
-### Step 3: Select Feature to Develop
+### Step 4: Select Feature to Develop
 
 Based on \`workflow/feature.json\`:
 - Prioritize \`in-progress\` status features
@@ -664,76 +1001,502 @@ Based on \`workflow/feature.json\`:
 
 ## Development Process
 
+### Feature Development Flow
+
 \`\`\`
 1. Update feature.json
    └─> Change selected feature status to "in-progress"
 
 2. Write code according to guidelines
-   └─> Follow workflow/structure/ guidelines
+   └─> Strictly follow workflow/structure/ development guidelines
+   └─> Frontend: Type safety, Hook standards, Component standards, Performance
+   └─> Backend: Directory structure, Type safety, Database operations, Logging
 
 3. Self-test
    └─> pnpm lint (must pass)
    └─> pnpm type-check (must pass)
    └─> Manual feature testing
 
-4. Commit code (human responsibility)
+4. Commit code
    └─> git add <files>
    └─> git commit -m "type(scope): description"
+       Format: feat/fix/docs/refactor/test/chore
 
 5. Update tracking files
-   └─> agent-progress: Record session work
-   └─> feature.json: Update feature status
+   └─> agent-progress: Record this session's work (include commit hashes)
+   └─> feature.json: Update feature status to "completed"
 \`\`\`
 
+### Code Quality Checklist
+
+**Must pass before commit**:
+- ✅ \`pnpm lint\` - 0 errors
+- ✅ \`pnpm type-check\` - No type errors
+- ✅ Manual feature testing passes
+
+**Frontend-specific checks**:
+- ✅ Use semantic HTML (\`<button>\` not \`<div role="button">\`)
+- ✅ Use Next.js \`<Image>\` instead of \`<img>\`
+- ✅ Import types from backend, don't redefine
+- ✅ Avoid non-null assertions \`!\`
+
+**Backend-specific checks**:
+- ✅ Strictly avoid non-null assertion \`!\`, use local variable extraction
+- ✅ All API inputs/outputs have Zod Schema
+- ✅ Use structured logging (\`logger\`), forbidden \`console.log\`
+- ✅ Database operations avoid \`await\` in loops
+- ✅ Update corresponding API documentation
+
 ---
 
 ## Session End
 
-### Checklist
+### Pre-end Checklist
 
-1. ✅ All code committed
+1. ✅ All code committed, commit message follows convention
 2. ✅ \`workflow/agent-progress/{developer}/progress-N.md\` updated
 3. ✅ \`workflow/feature.json\` status updated
 4. ✅ No lint/type-check errors
+5. ✅ Working directory clean (or WIP noted)
+
+### Update Tracking Files
+
+**agent-progress update**:
+- Write to your own directory: \`workflow/agent-progress/{developer}/\`
+- Include commit hashes in your session record
+- See template in \`workflow/agent-progress/index.md\`
+
+**feature.json update**:
+\`\`\`json
+{
+  "id": "feature-xxx",
+  "status": "completed",
+  "completedAt": "2025-11-28",
+  "commit": "abc1234"
+}
+\`\`\`
+
+Also update \`statistics\` field completion rate.
+
+---
+
+## File Descriptions
+
+### 1. agent-progress/ - Agent Work Progress
+
+**Purpose**: Record each AI Agent session's work content
+
+**Structure** (Multi-developer support):
+\`\`\`
+agent-progress/
+├── index.md              # Main index (Active Developers table)
+└── {developer}/          # Per-developer directory
+    ├── index.md          # Personal index
+    └── progress-N.md     # Progress files (sequential: 1, 2, 3...)
+\`\`\`
+
+**When to update**:
+- ✅ End of each session
+- ✅ Complete important feature
+- ✅ Fix important bug
+
+**How to update**:
+1. Get your developer name: \`./workflow/scripts/get-developer.sh\`
+2. Open your personal index: \`workflow/agent-progress/{developer}/index.md\`
+3. Add new session record to your active progress file
+4. ⚠️ **IMPORTANT: If file exceeds 2000 lines:**
+   - Create new file \`progress-{N+1}.md\`
+   - Update your personal index.md
+   - **Do NOT continue adding to a file over 2000 lines**
+
+**Record content**:
+- Summary: One-line description
+- Main changes: Files and change descriptions
+- Git commits: Commit hash and message (use \`git log\` to get)
+- Related features: ID in feature.json
+- Next steps: What to do next
+
+### 2. feature.json - Feature Tracking
+
+**Purpose**: Structured record of all feature completion status
+
+**When to update**:
+- ✅ Start developing new feature (planned → in-progress)
+- ✅ Complete feature (in-progress → completed)
+- ✅ Feature blocked (any status → blocked)
+- ✅ Add new planned feature (add planned)
+
+**How to update**:
+1. Modify corresponding feature's \`status\` field
+2. If completed, add \`completedAt\` and \`commit\` fields
+3. If blocked, add \`blockedReason\` field
+4. Recalculate \`statistics\` section values
+5. Update \`lastUpdated\` field to current date
+
+**Status flow**:
+\`\`\`
+planned → in-progress → completed
+   ↓           ↓            ↓
+ blocked ← blocked ← blocked
+\`\`\`
 
 ---
 
 ## Best Practices
 
-### DO
-- Read guidelines before coding
-- Update agent-progress after each session
-- Include commit hashes in progress records
-- Run lint and type-check before finishing
+### ✅ DO - Should Do
+
+1. **Before session start**:
+   - Check your identity: \`./workflow/scripts/get-developer.sh\`
+   - Read your agent-progress and feature.json
+   - Check recent git log: \`git log --oneline -20\`
+   - ⚠️ **MUST read** \`workflow/structure/[frontend|backend]/index.md\`
+   - ⚠️ **MUST read** specific sections in doc.md based on task
+
+2. **During development**:
+   - ⚠️ **Strictly follow** \`workflow/structure/\` frontend/backend guidelines
+   - Develop only one feature at a time
+   - Run lint and type-check before finishing
+
+3. **After development complete** (⚠️ AI should not commit, human is responsible):
+   - AI reminds human to test
+   - Human commits after testing passes
+   - After human commits, use \`/record-agent-flow\` to record progress
+   - Update feature.json status
+
+### ❌ DON'T - Should Not Do
+
+1. ⚠️ **Don't** skip reading \`workflow/structure/\` guidelines (CRITICAL VIOLATION)
+2. ⚠️ **Don't** let agent-progress single file exceed 2000 lines
+3. **Don't** skip reading context files
+4. **Don't** develop multiple unrelated features simultaneously
+5. **Don't** commit code with lint/type-check errors
+6. **Don't** forget to update tracking files
+7. ⚠️ **Don't** execute \`git commit\` - AI should not commit code
+   - Only allowed: \`git log\`, \`git status\`, \`git diff\`
+   - Human is responsible for testing and committing
+
+---
+
+## Error Recovery
+
+### Lint/Type Errors
+
+\`\`\`bash
+# Auto-fix formatting issues
+pnpm format
+
+# Auto-fix safe lint issues
+pnpm biome check --write --unsafe .
+
+# Check remaining issues
+pnpm lint
+\`\`\`
+
+### Git Issues
 
-### DON'T
-- Skip reading guidelines (CRITICAL VIOLATION)
-- Let agent-progress exceed 2000 lines
-- Commit code with lint/type-check errors
-- Execute \`git commit\` as AI - human reviews and commits
+\`\`\`bash
+# Undo last commit (keep changes)
+git reset --soft HEAD~1
+
+# Discard uncommitted changes
+git checkout -- <file>
+
+# View changes
+git diff
+git status
+\`\`\`
 
 ---
 
-## Common Commands
+## Quick Reference
+
+### Must-read Before Development
+
+| Task Type | Must-read Document | Line Numbers |
+|---------|---------|------|
+| New Frontend Query Hook | \`frontend/doc.md\` | (see index.md) |
+| New Frontend Mutation Hook | \`frontend/doc.md\` | (see index.md) |
+| New Frontend Component | \`frontend/doc.md\` | (see index.md) |
+| New Backend API | \`backend/doc.md\` | (see index.md) |
+| Database Batch Operations | \`backend/doc.md\` | (see index.md) |
+
+### Commit Convention
+
+\`\`\`bash
+git commit -m "type(scope): description"
+\`\`\`
+
+**Type**: feat, fix, docs, refactor, test, chore
+**Scope**: Module name (e.g., mail, auth, api)
+**Description**: Brief description
+
+### Common Commands
 
 \`\`\`bash
 # Development
 pnpm dev              # Start dev server
 pnpm build            # Production build
 pnpm lint             # Lint check
+pnpm format           # Format code
 pnpm type-check       # Type check
 
 # Git
-git log --oneline -20         # Recent commits
+git log --oneline -20         # Recent 20 commits
+git diff main...HEAD          # Diff with main
 git status                    # Working directory status
 \`\`\`
+
+---
+
+## Summary
+
+Following this workflow ensures:
+- ✅ Continuity across multiple sessions
+- ✅ Consistent code quality
+- ✅ Trackable progress
+- ✅ Easy recovery and rollback
+- ✅ Transparent team collaboration
+
+**Core Philosophy**: Read before write, follow standards, record promptly, develop incrementally
+`;
+    fs.writeFileSync(path.join(cwd, "workflow/flow.md"), content);
+}
+async function createOnboardingGuide(cwd) {
+    const content = `# AI Onboarding Guide for New Developers
+
+> **Purpose**: Help AI understand the workflow system, then guide first-time developers
+
+---
+
+## Part 1: AI Self-Learning (Read This First)
+
+### 1.1 What is This Workflow?
+
+This is a **multi-developer collaboration workflow system** based on [Anthropic Best Practices](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
+
+**Core Problem**: AI Agents have no persistent memory, each session is independent. Without handling:
+- New sessions don't know what was done before
+- May re-develop completed features
+- Code style may be inconsistent
+
+**Solution**: Use file system to simulate "persistent memory"
+
+\`\`\`
+workflow/
+├── agent-progress/           # Progress records (simulated memory)
+│   └── {developer}/          # Each developer has own directory
+│       ├── index.md          # Session history table
+│       └── progress-N.md     # Detailed records
+├── structure/                # Development guidelines
+│   ├── frontend/             # Frontend guidelines
+│   └── backend/              # Backend guidelines
+├── feature.json              # Feature tracking
+├── flow.md                   # Workflow specification
+└── .developer                # Local identity file (gitignore)
+\`\`\`
+
+### 1.2 Key Design Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Multi-developer Isolation** | Each developer/Agent has own directory, avoid conflicts |
+| **AI Doesn't Commit Code** | AI only develops, human tests and commits |
+| **Sequential Numbering** | Progress files use \`progress-1.md\`, \`progress-2.md\` (not dates) |
+| **2000 Line Limit** | Create new file when single file exceeds 2000 lines |
+
+### 1.3 Daily Workflow
+
+\`\`\`
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│  /init-agent           → AI reads context               │
+│       ↓                                                 │
+│  AI develops code      → Follow workflow/structure/     │
+│       ↓                                                 │
+│  /check-frontend       → Check frontend standards (opt) │
+│  /check-backend        → Check backend standards (opt)  │
+│       ↓                                                 │
+│  pnpm lint             → Check code quality             │
+│       ↓                                                 │
+│  👤 Human tests        → AI doesn't commit itself       │
+│       ↓                                                 │
+│  👤 Human git commit   → Commit after test passes       │
+│       ↓                                                 │
+│  /record-agent-flow    → Record progress (with hash)    │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+\`\`\`
+
+### 1.4 Available Slash Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| \`/init-agent\` | Initialize AI session, read project context | Every time starting work |
+| \`/onboard-developer\` | Guide new developer through initialization | First-time users |
+| \`/check-frontend\` | Check if frontend code follows standards | After frontend code is done |
+| \`/check-backend\` | Check if backend code follows standards | After backend code is done |
+| \`/record-agent-flow\` | Record progress to agent-progress | After human commits code |
+| \`/generate-frontend-structure\` | Auto-generate frontend guidelines | Setting up project standards |
+| \`/generate-backend-structure\` | Auto-generate backend guidelines | Setting up project standards |
+
+### 1.5 AI Permission Boundaries
+
+| Can Do ✅ | Cannot Do ❌ |
+|----------|-------------|
+| \`git log\` view history | \`git commit\` commit code |
+| \`git status\` view status | \`git push\` push code |
+| \`git diff\` view changes | \`git add\` stage files |
+| Write code | Commit without human testing |
+
+### 1.6 Related Document Locations
+
+| Document | Purpose | When to Read |
+|----------|---------|--------------|
+| \`init-agent.md\` | Complete initialization guide | Start of each session |
+| \`workflow/flow.md\` | Workflow specification | Need to understand process details |
+| \`workflow/structure/\` | Coding standards | Before writing code |
+
+---
+
+## Part 2: Identifying New Developers
+
+When the following occurs, developer may be first-time user:
+
+### 2.1 Auto Detection
+
+\`\`\`bash
+# Run this command, if error returned, it's a new developer
+./workflow/scripts/get-developer.sh
+
+# Error output:
+# ERROR: Developer not initialized. Run: ./workflow/scripts/init-developer.sh
+\`\`\`
+
+### 2.2 Proactive Inquiry
+
+Developer may say:
+- "How do I use this workflow?"
+- "I'm new, how do I start?"
+- "First time using, what do I need to do?"
+- "Do I need to initialize something?"
+
+---
+
+## Part 3: Guiding New Developers
+
+> When you confirm developer needs guidance, follow these steps
+
+### Step 1: Explain Concept (30 seconds)
+
+**AI should say**:
+
+> This project uses a multi-developer workflow system. Simply put:
+> 
+> - Each developer has their own progress directory
+> - AI helps write code, but **you test and commit**
+> - This ensures code quality, prevents AI from committing problematic code
+> 
+> Now let me help you initialize your developer identity.
+
+### Step 2: Choose Name
+
+**AI should ask**:
+
+> Please tell me your developer name:
+> - Use your name, like \`john-doe\`
+> - Only letters, numbers, hyphens, underscores allowed
+
+### Step 3: Run Initialization
+
+\`\`\`bash
+./workflow/scripts/init-developer.sh <developer-name>
+\`\`\`
+
+**AI should explain**:
+
+> The script created:
+> 1. Your identity file (stored locally, not committed to git)
+> 2. Your progress directory
+
+### Step 4: Verify Success
+
+\`\`\`bash
+./workflow/scripts/get-developer.sh
+# Should output developer's name
+\`\`\`
+
+### Step 5: Explain Daily Process and Common Commands
+
+**AI should say**:
+
+> Initialization complete! Future workflow:
+> 
+> 1. Every time starting work, run \`/init-agent\`
+> 2. AI helps write code
+> 3. After code is done, use \`/check-frontend\` or \`/check-backend\` to check standards
+> 4. You test the code
+> 5. After test passes, **you do git commit**
+> 6. After commit, run \`/record-agent-flow\` to record progress
+> 
+> **Remember**: AI won't execute git commit, that's your responsibility.
+
+---
+
+## Part 4: Quick Guide Template
+
+If developer is in a hurry, use this simplified version:
+
+**AI says**:
+
+> Quick start:
+> 
+> \`\`\`bash
+> # Initialize (only once)
+> ./workflow/scripts/init-developer.sh your-name
+> \`\`\`
+> 
+> Then develop normally:
+> - AI won't commit, you commit
+> - After commit use \`/record-agent-flow\` to record
+> 
+> Detailed docs: \`workflow/flow.md\`
+
+---
+
+## Part 5: FAQ
+
+### Q: Why can't AI commit code itself?
+
+> To ensure code quality. Humans can review and test before commit, preventing problematic code from entering codebase.
+
+### Q: Do I need to initialize every time?
+
+> No, only once. Identity info is stored locally, not committed to git.
+
+### Q: Will multi-person collaboration conflict?
+
+> No. Each developer has their own directory, only updates their own files.
+
+---
+
+## Part 6: Onboarding Completion Checklist
+
+Confirm all completed:
+
+- [ ] AI understands workflow (Part 1)
+- [ ] Identified developer needs guidance
+- [ ] Developer chose name
+- [ ] \`init-developer.sh\` ran successfully
+- [ ] \`get-developer.sh\` returns correct name
+- [ ] Developer understands AI won't commit
 `;
-    fs.writeFileSync(path.join(cwd, 'workflow/flow.md'), content);
+    fs.writeFileSync(path.join(cwd, "workflow/onboarding-guide.md"), content);
 }
 async function createWorkflowGitignore(cwd) {
     const content = `# Developer identity (local only)
 .developer
 `;
-    fs.writeFileSync(path.join(cwd, 'workflow/.gitignore'), content);
+    fs.writeFileSync(path.join(cwd, "workflow/.gitignore"), content);
 }
 //# sourceMappingURL=workflow.js.map