proagents 1.6.13 → 1.6.15

package/.proagents/.learning/global/common-patterns.template.json

@@ -0,0 +1,60 @@
+{
+  "_template_info": {
+    "description": "Template reference for common-patterns.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for common-patterns.json"
+  },
+
+  "$schema": "../schemas/patterns-schema.json",
+  "version": "1.0.0",
+  "updated_at": "2024-01-15T10:30:00Z",
+
+  "patterns": {
+    "component_patterns": [
+      {
+        "id": "pattern-id",
+        "name": "Pattern Name",
+        "frequency": 95,
+        "confidence": 0.98,
+        "template": "code template with {{placeholders}}"
+      }
+    ],
+    "api_patterns": [],
+    "error_handling": [],
+    "testing_patterns": []
+  },
+
+  "anti_patterns": [
+    {
+      "id": "anti-pattern-id",
+      "name": "Anti-pattern Name",
+      "detected_count": 0,
+      "suggestion": "How to fix",
+      "auto_suggest": true
+    }
+  ],
+
+  "learned_from": {
+    "codebase_analysis": 0,
+    "user_corrections": 0,
+    "explicit_teaching": 0
+  },
+
+  "_schema_notes": {
+    "patterns": {
+      "component_patterns": "React/Vue/etc component patterns",
+      "api_patterns": "API handler patterns",
+      "error_handling": "Error handling patterns",
+      "testing_patterns": "Test structure patterns"
+    },
+    "pattern_fields": {
+      "id": "Unique identifier",
+      "name": "Human-readable name",
+      "frequency": "How often used (0-100)",
+      "confidence": "AI confidence (0-1)",
+      "template": "Code template with {{placeholders}}"
+    },
+    "anti_patterns": "Patterns to avoid",
+    "learned_from": "Source of learning data"
+  }
+}

package/.proagents/.learning/global/user-preferences.template.json

@@ -0,0 +1,78 @@
+{
+  "_template_info": {
+    "description": "Template reference for user-preferences.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for user-preferences.json"
+  },
+
+  "$schema": "../schemas/user-preferences-schema.json",
+  "version": "1.0.0",
+  "updated_at": "2024-01-15T10:30:00Z",
+
+  "checkpoint_preferences": {
+    "usually_skips": ["after_requirements", "after_documentation"],
+    "always_reviews": ["after_design", "before_deployment"],
+    "auto_approve_conditions": [
+      {
+        "checkpoint": "after_analysis",
+        "condition": "files_changed < 5",
+        "confidence": 0.85
+      }
+    ]
+  },
+
+  "workflow_preferences": {
+    "preferred_mode": "full",
+    "skip_phases_for_bug_fixes": ["design", "documentation"],
+    "detail_level": "high",
+    "verbosity": "moderate"
+  },
+
+  "code_preferences": {
+    "naming_style": {
+      "components": "PascalCase",
+      "functions": "camelCase",
+      "constants": "UPPER_SNAKE_CASE",
+      "files": "kebab-case"
+    },
+    "formatting": {
+      "indent": 2,
+      "quotes": "single",
+      "semicolons": true,
+      "trailing_commas": "es5"
+    },
+    "patterns": {
+      "state_management": "zustand",
+      "data_fetching": "react-query",
+      "styling": "tailwind"
+    }
+  },
+
+  "review_preferences": {
+    "focus_areas": ["security", "performance", "accessibility"],
+    "thoroughness": "high",
+    "comment_style": "inline"
+  },
+
+  "notification_preferences": {
+    "on_checkpoint": true,
+    "on_completion": true,
+    "on_error": true,
+    "channels": ["terminal"]
+  },
+
+  "learning_consent": {
+    "track_corrections": true,
+    "track_patterns": true,
+    "share_anonymized": false
+  },
+
+  "_schema_notes": {
+    "checkpoint_preferences": "User's checkpoint review preferences",
+    "workflow_preferences": "How user prefers to work",
+    "code_preferences": "Coding style and patterns",
+    "review_preferences": "Code review settings",
+    "notification_preferences": "When to notify",
+    "learning_consent": "Privacy settings for learning"
+  }
+}

package/.proagents/AGENTS.md

@@ -0,0 +1,55 @@
+# ProAgents Commands for Codex
+
+This project uses ProAgents - an AI-agnostic development workflow framework.
+
+## MANDATORY: Every pa: Command Flow
+
+### BEFORE Any pa: Command (Auto-Sync)
+
+**Read these files FIRST before doing anything:**
+
+```bash
+cat .proagents/worklog/_context.md      # Current state
+cat .proagents/changelog/_recent.md     # Recent changes
+tail -10 .proagents/activity.log        # Recent activity
+```
+
+**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+
+### AFTER Any pa: Command (Auto-Log)
+
+**After EVERY file edit, IMMEDIATELY update these files:**
+
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/changelog/modules/[module].md` - Based on file path
+3. `.proagents/worklog/_context.md` - Update current state
+
+Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+
+## Essential Commands
+
+| Command | Action |
+|---------|--------|
+| `pa:feature "name"` | Start new feature workflow |
+| `pa:fix "bug"` | Quick bug fix mode |
+| `pa:doc` | Documentation options |
+| `pa:qa` | Quality assurance checks |
+| `pa:test` | Run test workflow |
+| `pa:deploy` | Deployment preparation |
+| `pa:status` | Show current progress |
+
+## Full Command Reference
+
+For complete command list, see: `./.proagents/AI_INSTRUCTIONS.md`
+
+## On `pa:` Command
+
+1. Read the corresponding file from `./.proagents/prompts/` or `./.proagents/workflow-modes/`
+2. Follow the workflow instructions
+3. Use project config from `./.proagents/proagents.config.yaml`
+
+## Key Files
+
+- `./.proagents/AI_INSTRUCTIONS.md` - Complete command reference
+- `./.proagents/WORKFLOW.md` - Full 10-phase workflow
+- `./.proagents/prompts/` - Phase-specific prompts

package/.proagents/AI_INSTRUCTIONS.md

@@ -41,6 +41,8 @@ tail -10 .proagents/activity.log 2>/dev/null
 5. AI logs to activity.log                          ← LOG ACTIVITY
 ```
 
+**Note:** When updating `_recent.md` or `_context.md`, first read the corresponding `*.template.md` file to use the latest format. See "Using Template Reference Files" section below.
+
 ---
 
 ## CRITICAL PRINCIPLE: ALWAYS DO, NEVER JUST TELL
@@ -155,6 +157,37 @@ AI immediately updates these files (no user prompt needed):
 4. .proagents/changelog/modules/X.md   ← Based on file path
 ```
 
+### Using Template Reference Files
+
+**IMPORTANT:** Template files (`*.template.md`, `*.template.json`) provide the latest format for user data files.
+
+| User Data File (EDIT THIS) | Template Reference (READ ONLY) |
+|----------------------------|-------------------------------|
+| `changelog/_recent.md` | `changelog/_recent.template.md` |
+| `worklog/_context.md` | `worklog/_context.template.md` |
+| `worklog/ai-stats.json` | `worklog/ai-stats.template.json` |
+| `active-features/_index.json` | `active-features/_index.template.json` |
+| `.learning/global/user-preferences.json` | `.learning/global/user-preferences.template.json` |
+| `.learning/global/common-patterns.json` | `.learning/global/common-patterns.template.json` |
+
+**How to use:**
+1. **Read the template FIRST** before creating/updating user data files
+2. **Apply the template format** to user data (structure, fields, sections)
+3. **NEVER modify template files** - they are READ ONLY (updated by framework)
+
+**Why templates exist:**
+- Templates get updated when ProAgents upgrades (new fields, better structure)
+- User data files are preserved during upgrades (your content stays safe)
+- AI always has access to the latest format by reading templates
+
+**Common mistake to avoid:**
+```
+WRONG: Edit _recent.template.md directly
+RIGHT: Read _recent.template.md, then edit _recent.md using that format
+```
+
+---
+
 ### Auto-Log Format for _recent.md:
 
 After editing `src/auth/login.ts`, AI prepends to `_recent.md`:

package/.proagents/active-features/_index.template.json

@@ -0,0 +1,75 @@
+{
+  "_template_info": {
+    "description": "Template reference for _index.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for _index.json"
+  },
+
+  "$schema": "./schemas/index-schema.json",
+  "version": "1.0.0",
+  "last_updated": "2024-03-13T10:30:00Z",
+
+  "active_features": [
+    {
+      "id": "feature-user-auth",
+      "name": "User Authentication",
+      "started_at": "2024-03-10T09:00:00Z",
+      "started_by": "claude",
+      "priority": "high",
+      "progress": 45,
+      "phase": "implementation"
+    }
+  ],
+
+  "paused_features": [
+    {
+      "id": "feature-dark-mode",
+      "name": "Dark Mode",
+      "paused_at": "2024-03-12T14:00:00Z",
+      "reason": "Waiting for design review"
+    }
+  ],
+
+  "completed_features": [
+    {
+      "id": "feature-login",
+      "name": "Login Page",
+      "completed_at": "2024-03-08T16:30:00Z",
+      "duration_days": 3
+    }
+  ],
+
+  "conflicts": {
+    "active": [],
+    "resolved": [
+      {
+        "files": ["src/auth.ts"],
+        "features": ["feature-user-auth", "feature-login"],
+        "resolved_at": "2024-03-08T12:00:00Z"
+      }
+    ]
+  },
+
+  "statistics": {
+    "total_active": 1,
+    "total_paused": 1,
+    "total_completed": 1,
+    "average_completion_days": 3,
+    "conflict_rate": 0.1
+  },
+
+  "_schema": {
+    "active_features": {
+      "type": "array",
+      "items": {
+        "id": "string - Unique feature ID",
+        "name": "string - Human-readable name",
+        "started_at": "string - ISO timestamp",
+        "started_by": "string - AI platform that started",
+        "priority": "string - low/medium/high",
+        "progress": "number - 0-100 percentage",
+        "phase": "string - planning/design/implementation/testing/review"
+      }
+    }
+  }
+}

package/.proagents/changelog/_recent.template.md

@@ -0,0 +1,51 @@
+# Recent Changes - Template Reference
+
+> This is the FORMAT REFERENCE for `_recent.md`.
+> AI should read this template when creating/updating `_recent.md`.
+> DO NOT modify this file - it gets updated with ProAgents upgrades.
+
+---
+
+## Expected Structure
+
+```markdown
+# Recent Changes
+
+> Last 10 changes across all features/modules.
+> Auto-updated by AI after each code change.
+
+---
+
+## Latest Changes
+
+### YYYY-MM-DD - [Change Type]
+**Module:** [auto-detected from file path]
+**AI:** [Platform] ([model])
+**Files:** path/to/file.ts (+lines, -lines)
+**Summary:** Brief description of change
+
+---
+```
+
+## Entry Format
+
+Each entry should include:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Date | ISO format | `2024-03-13` |
+| Change Type | bug-fix, feature, refactor, docs | `bug-fix` |
+| Module | Auto-detected from path | `auth`, `api`, `ui` |
+| AI | Platform and model | `Claude (opus-4)` |
+| Files | Changed files with line counts | `src/auth.ts (+15, -3)` |
+| Summary | Brief description | `Fixed login timeout issue` |
+
+## Auto-Update Rules
+
+1. **Prepend** new entries (newest first)
+2. **Keep only last 10** entries
+3. **Auto-detect module** from file path:
+   - `src/api/*` → api
+   - `src/auth/*` → auth
+   - `src/components/*` → ui
+4. **Update after every file edit**

package/.proagents/worklog/_context.template.md

@@ -0,0 +1,82 @@
+# Current Project Context - Template Reference
+
+> This is the FORMAT REFERENCE for `_context.md`.
+> AI should read this template when creating/updating `_context.md`.
+> DO NOT modify this file - it gets updated with ProAgents upgrades.
+
+---
+
+## Expected Structure
+
+```markdown
+# Current Project Context
+
+> **For AI Assistants:** Read this file first to understand current state.
+> **Auto-updated** after each code change.
+
+Last Updated: [ISO timestamp]
+Last AI: [Platform (model)]
+
+---
+
+## Quick Summary
+<!-- AI auto-generates - keep under 5 lines -->
+```
+Last: [Last action]
+Active: [Feature name or "No active features"]
+Pending: [N] tasks
+Tests: [Passing/Failing/Unknown]
+Status: [Current status]
+```
+
+---
+
+## Test Status
+<!-- AI updates after running tests -->
+```
+Status: [Passing/Failing/Unknown]
+Last Run: [Timestamp]
+Failing: [Test names or "None"]
+```
+
+---
+
+## Feature Progress
+<!-- AI auto-calculates -->
+```
+[Feature name]: [X]% ([done]/[total] tasks)
+```
+
+---
+
+## Active Work
+[Current active features or tasks]
+
+---
+
+## Recent Changes
+[Last 3-5 changes]
+
+---
+
+## Pending Items
+[Outstanding tasks]
+
+---
+
+## Quick Stats
+| Metric | Value |
+|--------|-------|
+| Active Features | [N] |
+| Completed Today | [N] |
+| Open Issues | [N] |
+```
+
+## Auto-Update Rules
+
+1. **Update `Last Updated`** with current timestamp
+2. **Update `Last AI`** with current platform
+3. **Keep Quick Summary under 5 lines**
+4. **Update Test Status after test runs**
+5. **Update Recent Changes with last 3-5 items**
+6. **Calculate Feature Progress from active-features/**

package/.proagents/worklog/ai-stats.template.json

@@ -0,0 +1,54 @@
+{
+  "_template_info": {
+    "description": "Template reference for ai-stats.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for ai-stats.json"
+  },
+
+  "ai_platforms": {
+    "claude": {
+      "sessions": 0,
+      "tasks_completed": 0,
+      "files_modified": 0,
+      "reverts": 0,
+      "avg_session_minutes": 0,
+      "last_session": "2024-03-13T10:30:00Z"
+    },
+    "chatgpt": {
+      "sessions": 0,
+      "tasks_completed": 0,
+      "files_modified": 0,
+      "reverts": 0,
+      "avg_session_minutes": 0,
+      "last_session": null
+    }
+  },
+
+  "totals": {
+    "total_sessions": 0,
+    "total_tasks": 0,
+    "total_files_modified": 0,
+    "total_reverts": 0
+  },
+
+  "_schema": {
+    "ai_platforms": {
+      "type": "object",
+      "description": "Stats per AI platform",
+      "properties": {
+        "[platform_id]": {
+          "sessions": "number - Total sessions by this AI",
+          "tasks_completed": "number - Tasks completed",
+          "files_modified": "number - Files modified",
+          "reverts": "number - Changes reverted by user",
+          "avg_session_minutes": "number - Average session duration",
+          "last_session": "string|null - ISO timestamp of last session"
+        }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "description": "Aggregated totals across all AIs"
+    }
+  }
+}

package/lib/commands/ai.js

@@ -24,13 +24,19 @@ export const AI_PLATFORMS = {
   web: {
     label: 'Web-based AI Platforms',
     platforms: [
-      { id: 'chatgpt', name: 'ChatGPT / Codex', file: 'CHATGPT.md', desc: 'OpenAI ChatGPT' },
+      { id: 'chatgpt', name: 'ChatGPT', file: 'CHATGPT.md', desc: 'OpenAI ChatGPT' },
       { id: 'gemini', name: 'Gemini', file: 'GEMINI.md', desc: 'Google Gemini' },
       { id: 'replit', name: 'Replit AI', file: 'REPLIT.md', desc: 'Replit Ghostwriter' },
       { id: 'bolt', name: 'Bolt.new', file: 'BOLT.md', desc: 'StackBlitz Bolt' },
       { id: 'lovable', name: 'Lovable', file: 'LOVABLE.md', desc: 'Lovable (GPT Engineer)' },
       { id: 'groq', name: 'Groq', file: 'GROQ.md', desc: 'Groq fast inference' },
     ]
+  },
+  cli: {
+    label: 'CLI-based AI Agents',
+    platforms: [
+      { id: 'codex', name: 'Codex CLI', file: 'AGENTS.md', desc: 'OpenAI Codex CLI' },
+    ]
   }
 };
 
@@ -39,6 +45,7 @@ export function getAllPlatforms() {
   return [
     ...AI_PLATFORMS.ide.platforms,
     ...AI_PLATFORMS.web.platforms,
+    ...AI_PLATFORMS.cli.platforms,
   ];
 }
 
@@ -47,6 +54,39 @@ export function getPlatformById(id) {
   return getAllPlatforms().find(p => p.id === id);
 }
 
+/**
+ * Detect current IDE from environment variables
+ * Returns platform ID if detected and it's in our AI_PLATFORMS config, null otherwise
+ * Note: VS Code is NOT an AI platform, so we skip it even if detected
+ */
+export function detectIDE() {
+  // Cursor IDE - check for Cursor-specific env vars
+  if (process.env.CURSOR_TRACE_ID || process.env.CURSOR_CHANNEL || process.env.CURSOR_SESSION_ID) {
+    return 'cursor';
+  }
+
+  // Windsurf IDE - Codeium's IDE
+  if (process.env.WINDSURF_SESSION_ID || process.env.CODEIUM_API_KEY ||
+      (process.env.TERM_PROGRAM && process.env.TERM_PROGRAM.toLowerCase().includes('windsurf'))) {
+    return 'windsurf';
+  }
+
+  // AWS Kiro IDE
+  if (process.env.KIRO_SESSION || process.env.KIRO_API_KEY ||
+      (process.env.TERM_PROGRAM && process.env.TERM_PROGRAM.toLowerCase().includes('kiro'))) {
+    return 'kiro';
+  }
+
+  // VS Code - NOT an AI platform, explicitly return null
+  // This prevents accidental detection as we don't want to create files for plain VS Code
+  if (process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_GIT_IPC_HANDLE) {
+    return null;
+  }
+
+  // No AI-powered IDE detected
+  return null;
+}
+
 /**
  * Interactive platform selection using readline
  * @param {string[]} previouslySelected - Previously selected platforms (from interrupted setup)
@@ -59,6 +99,21 @@ export async function selectPlatforms(previouslySelected = []) {
 
   const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
 
+  // Auto-detect IDE and pre-select it
+  const detectedIDE = detectIDE();
+  let autoSelected = [];
+
+  if (detectedIDE) {
+    const platform = getPlatformById(detectedIDE);
+    if (platform) {
+      console.log(chalk.green(`\n✓ Detected ${platform.name} IDE - auto-selected`));
+      autoSelected = [detectedIDE];
+    }
+  }
+
+  // Merge auto-detected with previously selected
+  const preselected = [...new Set([...autoSelected, ...(previouslySelected || [])])];
+
   console.log('\n' + chalk.bold('Which AI platform(s) do you use?'));
   console.log(chalk.gray('(Enter numbers separated by commas, or "all" for all platforms)\n'));
 
@@ -69,11 +124,18 @@ export async function selectPlatforms(previouslySelected = []) {
   // IDE-based platforms
   console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.ide.label}:`));
   for (const platform of AI_PLATFORMS.ide.platforms) {
-    const wasSelected = previouslySelected && previouslySelected.includes(platform.id);
-    const marker = wasSelected ? chalk.green(' ✓ (previously selected)') : '';
+    const isAutoDetected = autoSelected.includes(platform.id);
+    const wasPreviouslySelected = previouslySelected && previouslySelected.includes(platform.id);
+    const isPreselected = preselected.includes(platform.id);
+    let marker = '';
+    if (isAutoDetected) {
+      marker = chalk.green(' ✓ (auto-detected)');
+    } else if (wasPreviouslySelected) {
+      marker = chalk.green(' ✓ (previously selected)');
+    }
     console.log(chalk.white(`    ${index}. ${platform.name}`) + chalk.gray(` - ${platform.desc}`) + marker);
     indexMap[index] = platform.id;
-    if (wasSelected) preSelectedIndices.push(index);
+    if (isPreselected) preSelectedIndices.push(index);
     index++;
   }
 
@@ -82,27 +144,42 @@ export async function selectPlatforms(previouslySelected = []) {
   // Web-based platforms
   console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.web.label}:`));
   for (const platform of AI_PLATFORMS.web.platforms) {
-    const wasSelected = previouslySelected && previouslySelected.includes(platform.id);
-    const marker = wasSelected ? chalk.green(' ✓ (previously selected)') : '';
+    const wasPreviouslySelected = previouslySelected && previouslySelected.includes(platform.id);
+    const isPreselected = preselected.includes(platform.id);
+    const marker = wasPreviouslySelected ? chalk.green(' ✓ (previously selected)') : '';
     console.log(chalk.white(`    ${index}. ${platform.name}`) + chalk.gray(` - ${platform.desc}`) + marker);
     indexMap[index] = platform.id;
-    if (wasSelected) preSelectedIndices.push(index);
+    if (isPreselected) preSelectedIndices.push(index);
     index++;
   }
 
   console.log('');
 
-  // Show default based on previous selection
+  // CLI-based platforms
+  console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.cli.label}:`));
+  for (const platform of AI_PLATFORMS.cli.platforms) {
+    const wasPreviouslySelected = previouslySelected && previouslySelected.includes(platform.id);
+    const isPreselected = preselected.includes(platform.id);
+    const marker = wasPreviouslySelected ? chalk.green(' ✓ (previously selected)') : '';
+    console.log(chalk.white(`    ${index}. ${platform.name}`) + chalk.gray(` - ${platform.desc}`) + marker);
+    indexMap[index] = platform.id;
+    if (isPreselected) preSelectedIndices.push(index);
+    index++;
+  }
+
+  console.log('');
+
+  // Show default based on preselected (auto-detected + previously selected)
   const defaultHint = preSelectedIndices.length > 0
-    ? `Enter for previous: ${preSelectedIndices.join(',')}`
+    ? `Enter for selected: ${preSelectedIndices.join(',')}`
     : 'e.g., 1,2,3 or "all"';
 
   const answer = await question(chalk.yellow(`Your selection (${defaultHint}): `));
   rl.close();
 
-  // If user just pressed enter and we have previous selections, use them
+  // If user just pressed enter and we have preselected platforms, use them
   if (answer.trim() === '' && preSelectedIndices.length > 0) {
-    return previouslySelected;
+    return preselected;
   }
 
   if (answer.toLowerCase() === 'all') {
@@ -387,6 +464,21 @@ export function showAvailablePlatforms(currentIds) {
     index++;
   }
 
+  console.log('');
+
+  // CLI-based platforms
+  console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.cli.label}:`));
+  for (const platform of AI_PLATFORMS.cli.platforms) {
+    const status = currentIds.includes(platform.id)
+      ? chalk.green(' ✓ (installed)')
+      : chalk.gray(' (not installed)');
+    console.log(chalk.white(`    ${index}. ${platform.name}`) + status);
+    if (!currentIds.includes(platform.id)) {
+      available.push({ index, platform });
+    }
+    index++;
+  }
+
   return available;
 }
 

package/lib/commands/init.js

@@ -16,8 +16,131 @@ const PRESERVE_PATHS = [
   'cache',                     // Cached analysis
   'changelog',                 // Change history (user data)
   'worklog',                   // Work context (user data)
+  'sessions',                  // Session data
+  'backups',                   // User backups
 ];
 
+// Files within PRESERVE_PATHS that should always be UPDATED (framework files)
+// These patterns match files that should be overwritten with latest framework version
+const UPDATE_WITHIN_PRESERVED = [
+  'README.md',                 // Documentation
+  'entry-template.md',         // Changelog entry template
+  '*.template.md',             // All template markdown files
+  '*.template.json',           // All template JSON files
+  'schemas',                   // Schema folders
+];
+
+/**
+ * Backup user data before fresh install
+ * Returns object mapping path to temp backup location
+ */
+function backupUserData(proagentsDir) {
+  const preserved = {};
+  for (const path of PRESERVE_PATHS) {
+    const fullPath = join(proagentsDir, path);
+    if (existsSync(fullPath)) {
+      const tempPath = join(proagentsDir, '..', `.proagents-backup-${path.replace(/\//g, '-')}`);
+      try {
+        cpSync(fullPath, tempPath, { recursive: true });
+        preserved[path] = tempPath;
+      } catch (err) {
+        // Silently continue if backup fails
+      }
+    }
+  }
+  return preserved;
+}
+
+/**
+ * Restore user data after fresh install
+ */
+function restoreUserData(proagentsDir, preserved) {
+  for (const [path, tempPath] of Object.entries(preserved)) {
+    const fullPath = join(proagentsDir, path);
+    if (existsSync(tempPath)) {
+      try {
+        // Remove the framework's empty/default version
+        if (existsSync(fullPath)) {
+          rmSync(fullPath, { recursive: true, force: true });
+        }
+        // Restore user's data
+        cpSync(tempPath, fullPath, { recursive: true });
+        // Clean up temp backup
+        rmSync(tempPath, { recursive: true, force: true });
+      } catch (err) {
+        // Silently continue if restore fails
+      }
+    }
+  }
+}
+
+/**
+ * Update framework files within preserved paths
+ * After restoring user data, this copies framework files like README.md, *.template.*, schemas/
+ */
+function updateFrameworkInPreserved(sourceDir, proagentsDir) {
+  for (const preservedPath of PRESERVE_PATHS) {
+    const sourcePath = join(sourceDir, preservedPath);
+    const targetPath = join(proagentsDir, preservedPath);
+
+    if (!existsSync(sourcePath) || !existsSync(targetPath)) continue;
+
+    try {
+      // Update README.md if exists
+      const sourceReadme = join(sourcePath, 'README.md');
+      const targetReadme = join(targetPath, 'README.md');
+      if (existsSync(sourceReadme)) {
+        cpSync(sourceReadme, targetReadme, { force: true });
+      }
+
+      // Update entry-template.md (for changelog)
+      const sourceEntryTemplate = join(sourcePath, 'entry-template.md');
+      const targetEntryTemplate = join(targetPath, 'entry-template.md');
+      if (existsSync(sourceEntryTemplate)) {
+        cpSync(sourceEntryTemplate, targetEntryTemplate, { force: true });
+      }
+
+      // Update schemas folder if exists
+      const sourceSchemas = join(sourcePath, 'schemas');
+      const targetSchemas = join(targetPath, 'schemas');
+      if (existsSync(sourceSchemas)) {
+        if (existsSync(targetSchemas)) {
+          rmSync(targetSchemas, { recursive: true, force: true });
+        }
+        cpSync(sourceSchemas, targetSchemas, { recursive: true });
+      }
+
+      // Update all *.template.md and *.template.json files
+      if (existsSync(sourcePath)) {
+        const entries = readdirSync(sourcePath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile() && (entry.name.endsWith('.template.md') || entry.name.endsWith('.template.json'))) {
+            cpSync(join(sourcePath, entry.name), join(targetPath, entry.name), { force: true });
+          }
+          // Also check subdirectories (like .learning/global/)
+          if (entry.isDirectory()) {
+            const subPath = join(sourcePath, entry.name);
+            const subTargetPath = join(targetPath, entry.name);
+            if (existsSync(subPath)) {
+              const subEntries = readdirSync(subPath, { withFileTypes: true });
+              for (const subEntry of subEntries) {
+                if (subEntry.isFile() && (subEntry.name.endsWith('.template.md') || subEntry.name.endsWith('.template.json'))) {
+                  if (!existsSync(subTargetPath)) {
+                    mkdirSync(subTargetPath, { recursive: true });
+                  }
+                  cpSync(join(subPath, subEntry.name), join(subTargetPath, subEntry.name), { force: true });
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (err) {
+      // Silently continue if update fails
+    }
+  }
+}
+
 // Config file is handled specially - merged not preserved
 const CONFIG_FILE = 'proagents.config.yaml';
 
@@ -90,6 +213,7 @@ const FRAMEWORK_FILES = [
   'GETTING-STARTED-STORY.md',
   'slash-commands.json',
   'AI_INSTRUCTIONS.md',  // Universal instructions kept for reference
+  'AGENTS.md',           // Universal AI instruction file (works with most AI platforms)
 ];
 
 // Project type definitions for detection
@@ -611,7 +735,7 @@ function checkIncompleteSetup(targetDir) {
   }
 
   // Check 2: No AI instruction files at all = incomplete
-  const aiFiles = ['CLAUDE.md', '.cursorrules', '.windsurfrules', 'CHATGPT.md', 'GEMINI.md'];
+  const aiFiles = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', '.windsurfrules', 'CHATGPT.md', 'GEMINI.md'];
   const hasAnyAiFile = aiFiles.some(f => existsSync(join(targetDir, f)));
   if (!hasAnyAiFile) {
     return true;
@@ -667,6 +791,27 @@ async function promptIncompleteSetupChoice() {
   return 'continue';
 }
 
+/**
+ * Confirm destructive "Restart fresh" action
+ */
+async function confirmRestartFresh() {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
+
+  console.log(chalk.red.bold('\n⚠️  WARNING: This will DELETE all data in .proagents/'));
+  console.log(chalk.yellow('   Including: changelog, worklog, sessions, learning data, etc.'));
+  console.log(chalk.gray('   This action cannot be undone.\n'));
+
+  const answer = await question(chalk.red('Type "DELETE" to confirm, or press Enter to cancel: '));
+  rl.close();
+
+  return answer.trim().toUpperCase() === 'DELETE';
+}
+
 /**
  * Prompt user for .gitignore preference
  */
@@ -981,6 +1126,12 @@ export async function initCommand(options = {}) {
         console.log(chalk.cyan('\nContinuing setup...\n'));
         // Fall through to fresh install (but keep .proagents folder)
       } else if (choice === 'restart') {
+        // Confirm destructive action
+        const confirmed = await confirmRestartFresh();
+        if (!confirmed) {
+          console.log(chalk.yellow('\nCancelled. No changes made.\n'));
+          return;
+        }
         console.log(chalk.cyan('\nRestarting fresh setup...\n'));
         rmSync(proagentsDir, { recursive: true, force: true });
         // Fall through to fresh install
@@ -1026,7 +1177,21 @@ export async function initCommand(options = {}) {
 
     // Fresh install or force overwrite
     console.log(chalk.gray('Copying framework files...'));
+
+    // Backup user data if .proagents exists (to preserve changelog, worklog, etc.)
+    const userDataBackup = existsSync(proagentsDir) ? backupUserData(proagentsDir) : {};
+
     cpSync(sourceDir, proagentsDir, { recursive: true, force: true });
+
+    // Restore user data after framework copy
+    if (Object.keys(userDataBackup).length > 0) {
+      restoreUserData(proagentsDir, userDataBackup);
+      // Update framework files within preserved paths (README.md, templates, schemas)
+      updateFrameworkInPreserved(sourceDir, proagentsDir);
+      console.log(chalk.green('✓ Preserved user data (changelog, worklog, sessions, etc.)'));
+      console.log(chalk.green('✓ Updated templates and documentation in preserved folders'));
+    }
+
     console.log(chalk.green('✓ Framework files copied to ./.proagents/'));
 
     // Create config if not skipped
@@ -1398,6 +1563,9 @@ async function smartUpdate(sourceDir, targetDir) {
     }
   }
 
+  // Update framework files within preserved paths (templates, README, schemas)
+  updateFrameworkInPreserved(sourceDir, targetDir);
+
   console.log(chalk.gray('\nTip: Use "proagents ai add" to add more AI platforms'));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proagents",
-  "version": "1.6.13",
+  "version": "1.6.15",
   "description": "AI-agnostic development workflow framework that automates the full software development lifecycle",
   "type": "module",
   "main": "lib/index.js",