proagents 1.5.0 → 1.6.1

package/{proagents → .proagents}/team/ide-setup/cursor.md

@@ -70,7 +70,7 @@ Cursor's AI chat integrates well with ProAgents:
 
 "Check the ProAgents workflow status"
 
-"Apply the coding standards from proagents/standards/"
+"Apply the coding standards from .proagents/standards/"
 ```
 
 ### Codebase Context
@@ -81,7 +81,7 @@ Cursor indexes your codebase for context. Ensure ProAgents files are indexed:
 {
   "cursor.ai.includePaths": [
     "src/**",
-    "proagents/**"
+    ".proagents/**"
   ],
   "cursor.ai.excludePaths": [
     "node_modules/**",
@@ -130,7 +130,7 @@ This is a [project type] project using [technologies].
 - Use TypeScript with strict mode
 - Follow functional programming patterns
 - Use Tailwind CSS for styling
-- Follow the patterns in proagents/standards/
+- Follow the patterns in .proagents/standards/
 
 # Testing
 - Write tests using Vitest
@@ -143,9 +143,9 @@ This is a [project type] project using [technologies].
 - Types in src/types/
 
 # ProAgents
-- Follow the workflow in proagents/WORKFLOW.md
-- Check proagents/standards/ for coding guidelines
-- Use proagents/checklists/ before completing phases
+- Follow the workflow in .proagents/WORKFLOW.md
+- Check .proagents/standards/ for coding guidelines
+- Use .proagents/checklists/ before completing phases
 ```
 
 ---
@@ -163,7 +163,7 @@ Please help me:
 3. Identify files that need changes
 4. Create the implementation plan
 
-Reference: proagents/prompts/04-planning.md
+Reference: .proagents/prompts/04-planning.md
 ```
 
 ### Code Review
@@ -174,8 +174,8 @@ Review this code following ProAgents standards:
 [paste code]
 
 Check against:
-- proagents/standards/coding-standards.md
-- proagents/checklists/code-review.md
+- .proagents/standards/coding-standards.md
+- .proagents/checklists/code-review.md
 
 Provide specific feedback and suggestions.
 ```
@@ -187,7 +187,7 @@ I'm encountering this error:
 
 [error message]
 
-Help me debug following proagents/prompts/debugging/systematic.md
+Help me debug following .proagents/prompts/debugging/systematic.md
 
 1. Analyze the error
 2. Identify potential causes
@@ -208,8 +208,8 @@ Cursor's Composer mode is powerful for multi-file changes:
 3. Reference ProAgents docs:
    ```
    Implement [feature] following:
-   - proagents/standards/react-nextjs.md for code style
-   - proagents/prompts/05-implementation.md for approach
+   - .proagents/standards/react-nextjs.md for code style
+   - .proagents/prompts/05-implementation.md for approach
    ```
 4. Review proposed changes
 5. Apply changes
@@ -233,15 +233,15 @@ Create `.cursor/settings.json`:
   "editor.defaultFormatter": "esbenp.prettier-vscode",
 
   "cursor.ai.contextFiles": [
-    "proagents/standards/*.md",
-    "proagents/prompts/*.md",
+    ".proagents/standards/*.md",
+    ".proagents/prompts/*.md",
     "README.md",
     "package.json"
   ],
 
   "cursor.composer.includePaths": [
     "src/**/*.{ts,tsx}",
-    "proagents/**/*.md"
+    ".proagents/**/*.md"
   ]
 }
 ```

package/README.md

@@ -11,17 +11,32 @@ A portable, universal development workflow framework that works with **any AI pl
 
 ## Installation
 
+No install required. Just run:
+
 ```bash
-# Initialize in your project
 npx proagents init
+```
+
+Or with a template:
 
-# Or with a template
+```bash
 npx proagents init --template nextjs-saas
+```
 
-# Install globally (optional)
-npm install -g proagents
+### Upgrading from v1.5.x
+
+Version 1.6.0 renamed `proagents/` to `.proagents/` (following `.github`, `.vscode` convention).
+
+```bash
+cd your-project
+npx proagents migrate
 ```
 
+**What migration does:**
+- Renames `proagents/` → `.proagents/`
+- Updates paths in `README.md`, `CLAUDE.md`, `.cursorrules`
+- Preserves all your existing configurations
+
 ---
 
 ## Quick Start
@@ -33,7 +48,7 @@ cd your-project
 npx proagents init
 ```
 
-This creates a `./proagents/` folder with workflow files, and prompts for:
+This creates a `./.proagents/` folder with workflow files, and prompts for:
 - Project name and type (auto-detected)
 - Tech stack (API style, database, styling, auth, etc.)
 - AI platforms to use (Claude, Cursor, Gemini, etc.)
@@ -411,7 +426,7 @@ Type these in any AI assistant (Claude, ChatGPT, Gemini, Cursor, etc.):
 | `pa:tech-debt` | Scan for technical debt |
 | `pa:security-scan` | Run security checklist |
 
-Define your own in `./proagents/custom-commands.yaml`
+Define your own in `./.proagents/custom-commands.yaml`
 
 ---
 
@@ -421,13 +436,13 @@ After initialization, these files help AI understand your project:
 
 | File | Purpose | AI Should |
 |------|---------|-----------|
-| `proagents/context.md` | Persistent project knowledge | **Read first every session!** |
-| `proagents/feedback.md` | Past corrections & preferences | Learn from mistakes |
-| `proagents/watchlist.yaml` | Protected files list | Ask before modifying |
-| `proagents/activity.log` | AI activity history | Check for conflicts |
-| `proagents/decisions.md` | Architectural decisions | Understand why choices were made |
-| `proagents/errors.md` | Past errors & solutions | Find solutions faster |
-| `proagents/handoff.md` | Handoff notes | Continue where another AI left off |
+| `.proagents/context.md` | Persistent project knowledge | **Read first every session!** |
+| `.proagents/feedback.md` | Past corrections & preferences | Learn from mistakes |
+| `.proagents/watchlist.yaml` | Protected files list | Ask before modifying |
+| `.proagents/activity.log` | AI activity history | Check for conflicts |
+| `.proagents/decisions.md` | Architectural decisions | Understand why choices were made |
+| `.proagents/errors.md` | Past errors & solutions | Find solutions faster |
+| `.proagents/handoff.md` | Handoff notes | Continue where another AI left off |
 
 ---
 
@@ -435,7 +450,7 @@ After initialization, these files help AI understand your project:
 
 ```
 your-project/
-├── proagents/
+├── .proagents/
 │   ├── proagents.config.yaml   # Project configuration
 │   ├── AI_INSTRUCTIONS.md      # Instructions for all AIs
 │   ├── PROAGENTS.md            # Quick command reference
@@ -525,10 +540,10 @@ platforms:
 
 | Document | Description |
 |----------|-------------|
-| [Getting Started Story](./proagents/GETTING-STARTED-STORY.md) | Narrative walkthrough |
-| [Complete Workflow](./proagents/WORKFLOW.md) | 10-phase workflow guide |
-| [AI Instructions](./proagents/AI_INSTRUCTIONS.md) | Full AI command reference |
-| [Examples](./proagents/examples/) | Project-specific walkthroughs |
+| [Getting Started Story](./.proagents/GETTING-STARTED-STORY.md) | Narrative walkthrough |
+| [Complete Workflow](./.proagents/WORKFLOW.md) | 10-phase workflow guide |
+| [AI Instructions](./.proagents/AI_INSTRUCTIONS.md) | Full AI command reference |
+| [Examples](./.proagents/examples/) | Project-specific walkthroughs |
 
 ---
 

package/bin/proagents.js

@@ -11,6 +11,7 @@ import { uninstallCommand } from '../lib/commands/uninstall.js';
 import { configListCommand, configShowCommand, configEditCommand, configSetCommand, configGetCommand, configSetupCommand, configCustomizeCommand } from '../lib/commands/config.js';
 import { doctorCommand } from '../lib/commands/doctor.js';
 import { upgradeCommand } from '../lib/commands/upgrade.js';
+import { migrateCommand } from '../lib/commands/migrate.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -83,8 +84,8 @@ program
   .action(() => {
     console.log('\nProAgents Documentation');
     console.log('=======================\n');
-    console.log('Local: ./proagents/README.md');
-    console.log('Workflow: ./proagents/WORKFLOW.md');
+    console.log('Local: ./.proagents/README.md');
+    console.log('Workflow: ./.proagents/WORKFLOW.md');
     console.log('GitHub: https://github.com/prakashpro3/proAgents\n');
   });
 
@@ -170,8 +171,15 @@ program
 // Upgrade command
 program
   .command('upgrade')
-  .description('Upgrade proagents folder to latest version')
+  .description('Upgrade .proagents folder to latest version')
   .option('-f, --force', 'Skip confirmation prompt')
   .action(upgradeCommand);
 
+// Migrate command
+program
+  .command('migrate')
+  .description('Migrate from proagents/ to .proagents/ folder structure')
+  .option('-f, --force', 'Skip confirmation prompt')
+  .action(migrateCommand);
+
 program.parse();

package/lib/commands/ai.js

@@ -292,8 +292,8 @@ export function showAvailablePlatforms(currentIds) {
  */
 export async function aiAddCommand() {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
-  const sourceDir = join(__dirname, '..', '..', 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
+  const sourceDir = join(__dirname, '..', '..', '.proagents');
   const configPath = join(proagentsDir, 'proagents.config.yaml');
 
   // Check if proagents is initialized
@@ -369,7 +369,7 @@ export async function aiAddCommand() {
  */
 export function aiListCommand() {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
   const configPath = join(proagentsDir, 'proagents.config.yaml');
 
   const currentIds = loadPlatformConfig(configPath);
@@ -386,7 +386,7 @@ export function aiListCommand() {
  */
 export async function aiRemoveCommand() {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
   const configPath = join(proagentsDir, 'proagents.config.yaml');
 
   if (!existsSync(proagentsDir)) {

package/lib/commands/config.js

@@ -14,7 +14,7 @@ const __dirname = dirname(__filename);
  */
 export function configListCommand() {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
 
   console.log('\n' + chalk.bold.blue('ProAgents Configuration Options'));
   console.log(chalk.blue('================================\n'));
@@ -30,10 +30,10 @@ export function configListCommand() {
   console.log(chalk.gray('   ─────────────────────────────────────────'));
   const configPath = join(proagentsDir, 'proagents.config.yaml');
   if (existsSync(configPath)) {
-    console.log(chalk.green('   ✓ ') + chalk.white('proagents/proagents.config.yaml'));
+    console.log(chalk.green('   ✓ ') + chalk.white('.proagents/proagents.config.yaml'));
     console.log(chalk.gray('     Checkpoints, git settings, parallel features, etc.\n'));
   } else {
-    console.log(chalk.yellow('   ○ ') + chalk.white('proagents/proagents.config.yaml') + chalk.gray(' (not created)\n'));
+    console.log(chalk.yellow('   ○ ') + chalk.white('.proagents/proagents.config.yaml') + chalk.gray(' (not created)\n'));
   }
 
   // 2. AI Platforms
@@ -161,9 +161,9 @@ export function configListCommand() {
   for (const item of preserved) {
     const fullPath = join(proagentsDir, item.path);
     if (existsSync(fullPath)) {
-      console.log(chalk.green('   ✓ ') + chalk.white(`proagents/${item.path}/`) + chalk.gray(` - ${item.desc}`));
+      console.log(chalk.green('   ✓ ') + chalk.white(`.proagents/${item.path}/`) + chalk.gray(` - ${item.desc}`));
     } else {
-      console.log(chalk.yellow('   ○ ') + chalk.white(`proagents/${item.path}/`) + chalk.gray(` - ${item.desc} (empty)`));
+      console.log(chalk.yellow('   ○ ') + chalk.white(`.proagents/${item.path}/`) + chalk.gray(` - ${item.desc} (empty)`));
     }
   }
   console.log('');
@@ -173,8 +173,8 @@ export function configListCommand() {
   console.log(chalk.white('Legend: ') + chalk.green('✓ customized  ') + chalk.yellow('○ using default'));
   console.log('');
   console.log(chalk.gray('To customize a template:'));
-  console.log(chalk.cyan('  cp proagents/config/standards/coding-standards.template.md \\'));
-  console.log(chalk.cyan('     proagents/config/standards/coding-standards.md'));
+  console.log(chalk.cyan('  cp .proagents/config/standards/coding-standards.template.md \\'));
+  console.log(chalk.cyan('     .proagents/config/standards/coding-standards.md'));
   console.log(chalk.gray('\nThen edit the new file with your settings.\n'));
 }
 
@@ -184,7 +184,7 @@ export function configListCommand() {
  */
 export function configShowCommand() {
   const targetDir = process.cwd();
-  const configPath = join(targetDir, 'proagents', 'proagents.config.yaml');
+  const configPath = join(targetDir, '.proagents', 'proagents.config.yaml');
 
   console.log('\n' + chalk.bold.blue('ProAgents Current Configuration'));
   console.log(chalk.blue('================================\n'));
@@ -198,7 +198,7 @@ export function configShowCommand() {
     const content = readFileSync(configPath, 'utf-8');
     const config = yaml.load(content);
 
-    console.log(chalk.cyan('File: ') + chalk.white('proagents/proagents.config.yaml\n'));
+    console.log(chalk.cyan('File: ') + chalk.white('.proagents/proagents.config.yaml\n'));
     console.log(chalk.gray('─────────────────────────────────────────────\n'));
     console.log(content);
   } catch (error) {
@@ -212,7 +212,7 @@ export function configShowCommand() {
  */
 export function configEditCommand() {
   const targetDir = process.cwd();
-  const configPath = join(targetDir, 'proagents', 'proagents.config.yaml');
+  const configPath = join(targetDir, '.proagents', 'proagents.config.yaml');
 
   if (!existsSync(configPath)) {
     console.log(chalk.yellow('\nConfig file not found. Run "proagents init" first.\n'));
@@ -220,8 +220,8 @@ export function configEditCommand() {
   }
 
   console.log(chalk.cyan('\nTo edit configuration:\n'));
-  console.log(chalk.white('  Open: ') + chalk.green('proagents/proagents.config.yaml'));
-  console.log(chalk.white('  Docs: ') + chalk.green('proagents/config/README.md\n'));
+  console.log(chalk.white('  Open: ') + chalk.green('.proagents/proagents.config.yaml'));
+  console.log(chalk.white('  Docs: ') + chalk.green('.proagents/config/README.md\n'));
 }
 
 /**
@@ -261,7 +261,7 @@ function parseValue(value) {
  */
 export function configSetCommand(key, value) {
   const targetDir = process.cwd();
-  const configPath = join(targetDir, 'proagents', 'proagents.config.yaml');
+  const configPath = join(targetDir, '.proagents', 'proagents.config.yaml');
 
   console.log('');
 
@@ -297,7 +297,7 @@ export function configSetCommand(key, value) {
  */
 export function configGetCommand(key) {
   const targetDir = process.cwd();
-  const configPath = join(targetDir, 'proagents', 'proagents.config.yaml');
+  const configPath = join(targetDir, '.proagents', 'proagents.config.yaml');
 
   console.log('');
 
@@ -330,12 +330,12 @@ export function configGetCommand(key) {
  */
 export async function configSetupCommand() {
   const targetDir = process.cwd();
-  const configPath = join(targetDir, 'proagents', 'proagents.config.yaml');
+  const configPath = join(targetDir, '.proagents', 'proagents.config.yaml');
 
   console.log('\n' + chalk.bold.blue('ProAgents Configuration Wizard'));
   console.log(chalk.blue('===============================\n'));
 
-  if (!existsSync(join(targetDir, 'proagents'))) {
+  if (!existsSync(join(targetDir, '.proagents'))) {
     console.log(chalk.yellow('ProAgents not initialized. Run "proagents init" first.\n'));
     return;
   }
@@ -477,7 +477,7 @@ const CUSTOMIZABLE_TEMPLATES = {
  */
 export async function configCustomizeCommand() {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
 
   console.log('\n' + chalk.bold.blue('ProAgents Template Customization'));
   console.log(chalk.blue('=================================\n'));

package/lib/commands/doctor.js

@@ -23,16 +23,16 @@ const PLATFORM_FILES = {
  * Check if ProAgents is installed
  */
 function checkInstallation(targetDir) {
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
   const configPath = join(targetDir, 'proagents.config.yaml');
 
   const checks = [];
 
   // Check proagents folder
   if (existsSync(proagentsDir)) {
-    checks.push({ name: 'ProAgents folder', status: 'ok', message: './proagents/ exists' });
+    checks.push({ name: 'ProAgents folder', status: 'ok', message: './.proagents/ exists' });
   } else {
-    checks.push({ name: 'ProAgents folder', status: 'error', message: './proagents/ not found. Run: npx proagents init' });
+    checks.push({ name: 'ProAgents folder', status: 'error', message: './.proagents/ not found. Run: npx proagents init' });
   }
 
   // Check config file

package/lib/commands/feature.js

@@ -7,7 +7,7 @@ import chalk from 'chalk';
  */
 export async function featureCommand(action, name = '') {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
   const activeFeaturesDir = join(proagentsDir, 'active-features');
 
   // Check if initialized
@@ -82,7 +82,7 @@ pa:feature "${name}"
 Or paste this to your AI:
 
 I want to start a new feature: "${name}"
-Please follow the ProAgents workflow in ./proagents/
+Please follow the ProAgents workflow in ./.proagents/
 Start with Phase 1: Analysis
 `));
   console.log(chalk.cyan('─'.repeat(50)) + '\n');

package/lib/commands/fix.js

@@ -7,7 +7,7 @@ import chalk from 'chalk';
  */
 export async function fixCommand(description, options = {}) {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
 
   // Check if initialized
   if (!existsSync(proagentsDir)) {
@@ -27,7 +27,7 @@ export async function fixCommand(description, options = {}) {
 pa:feature "Fix: ${description}"
 
 This bug fix has been upgraded to full workflow mode.
-Please follow all phases in ./proagents/WORKFLOW.md
+Please follow all phases in ./.proagents/WORKFLOW.md
 `));
     console.log(chalk.cyan('─'.repeat(50)) + '\n');
     return;
@@ -45,7 +45,7 @@ Or paste this to your AI:
 
 I need to fix a bug: "${description}"
 
-Please follow the Bug Fix Fast Track in ./proagents/workflow-modes/entry-modes.md:
+Please follow the Bug Fix Fast Track in ./.proagents/workflow-modes/entry-modes.md:
 1. Context Scan - Identify affected files
 2. Root Cause Analysis - Find the bug source
 3. Fix Implementation - Apply minimal fix

package/lib/commands/help.js

@@ -117,8 +117,8 @@ export async function helpCommand() {
   // More info
   console.log(chalk.bold.white('More Information'));
   console.log(chalk.gray('─'.repeat(40)));
-  console.log('Documentation: ' + chalk.cyan('./proagents/README.md'));
-  console.log('Full Workflow: ' + chalk.cyan('./proagents/WORKFLOW.md'));
+  console.log('Documentation: ' + chalk.cyan('./.proagents/README.md'));
+  console.log('Full Workflow: ' + chalk.cyan('./.proagents/WORKFLOW.md'));
   console.log('GitHub: ' + chalk.cyan('https://github.com/prakashpro3/proAgents'));
   console.log('');
 }

package/lib/commands/init.js

@@ -798,8 +798,8 @@ function saveProjectConfig(projectConfig, configPath) {
  */
 export async function initCommand(options = {}) {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
-  const sourceDir = join(__dirname, '..', '..', 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
+  const sourceDir = join(__dirname, '..', '..', '.proagents');
 
   console.log('\n' + chalk.bold.blue('ProAgents Initialization'));
   console.log(chalk.blue('========================\n'));
@@ -836,7 +836,7 @@ export async function initCommand(options = {}) {
     // Fresh install or force overwrite
     console.log(chalk.gray('Copying framework files...'));
     cpSync(sourceDir, proagentsDir, { recursive: true, force: true });
-    console.log(chalk.green('✓ Framework files copied to ./proagents/'));
+    console.log(chalk.green('✓ Framework files copied to ./.proagents/'));
 
     // Create config if not skipped
     if (!options.skipConfig) {
@@ -964,7 +964,7 @@ This project uses [ProAgents](https://github.com/prakashpro3/proAgents). Command
 | \`pa:status\` | Show progress |
 | \`pa:release\` | Generate release notes |
 
-For detailed commands, see \`./proagents/PROAGENTS.md\`
+For detailed commands, see \`./.proagents/PROAGENTS.md\`
 <!-- PROAGENTS:END -->
 
 `;

package/lib/commands/migrate.js

@@ -0,0 +1,104 @@
+import { existsSync, renameSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { createInterface } from 'readline';
+
+/**
+ * Migrate from proagents/ to .proagents/
+ */
+export async function migrateCommand(options = {}) {
+  const targetDir = process.cwd();
+  const oldDir = join(targetDir, 'proagents');
+  const newDir = join(targetDir, '.proagents');
+
+  console.log(chalk.bold('\nProAgents Migration'));
+  console.log(chalk.gray('==================\n'));
+
+  // Check if migration is needed
+  const hasOldDir = existsSync(oldDir);
+  const hasNewDir = existsSync(newDir);
+
+  if (!hasOldDir && hasNewDir) {
+    console.log(chalk.green('✓ Already using .proagents/ folder. No migration needed.\n'));
+    return;
+  }
+
+  if (!hasOldDir && !hasNewDir) {
+    console.log(chalk.yellow('⚠ No proagents folder found. Run `npx proagents init` to get started.\n'));
+    return;
+  }
+
+  if (hasOldDir && hasNewDir) {
+    console.log(chalk.red('✗ Both proagents/ and .proagents/ folders exist.'));
+    console.log(chalk.gray('  Please manually remove one before migrating.\n'));
+    return;
+  }
+
+  // Migration needed
+  console.log(chalk.cyan('Migration detected: proagents/ → .proagents/\n'));
+  console.log(chalk.gray('This will:'));
+  console.log(chalk.gray('  1. Rename proagents/ to .proagents/'));
+  console.log(chalk.gray('  2. Update references in README.md'));
+  console.log(chalk.gray('  3. Keep all your customizations intact\n'));
+
+  // Confirm unless --force
+  if (!options.force) {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    const answer = await new Promise(resolve => {
+      rl.question(chalk.yellow('Proceed with migration? (y/n): '), resolve);
+    });
+    rl.close();
+
+    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+      console.log(chalk.gray('\nMigration cancelled.\n'));
+      return;
+    }
+  }
+
+  try {
+    // 1. Rename the folder
+    console.log(chalk.gray('\nRenaming proagents/ to .proagents/...'));
+    renameSync(oldDir, newDir);
+    console.log(chalk.green('✓ Folder renamed'));
+
+    // 2. Update README.md references
+    const readmePath = join(targetDir, 'README.md');
+    if (existsSync(readmePath)) {
+      console.log(chalk.gray('Updating README.md references...'));
+      let content = readFileSync(readmePath, 'utf-8');
+      content = content.replace(/\.\/proagents\//g, './.proagents/');
+      content = content.replace(/`proagents\//g, '`.proagents/');
+      writeFileSync(readmePath, content);
+      console.log(chalk.green('✓ README.md updated'));
+    }
+
+    // 3. Update any AI instruction files
+    const aiFiles = ['CLAUDE.md', '.cursorrules', 'CHATGPT.md', 'GEMINI.md'];
+    for (const file of aiFiles) {
+      const filePath = join(targetDir, file);
+      if (existsSync(filePath)) {
+        let content = readFileSync(filePath, 'utf-8');
+        if (content.includes('./proagents/') || content.includes('`proagents/')) {
+          content = content.replace(/\.\/proagents\//g, './.proagents/');
+          content = content.replace(/`proagents\//g, '`.proagents/');
+          writeFileSync(filePath, content);
+          console.log(chalk.green(`✓ ${file} updated`));
+        }
+      }
+    }
+
+    console.log(chalk.green('\n✓ Migration complete!\n'));
+    console.log(chalk.gray('Your project now uses the new .proagents/ folder structure.'));
+    console.log(chalk.gray('This follows the convention of .github/, .vscode/, .claude/, etc.\n'));
+
+  } catch (error) {
+    console.error(chalk.red('\n✗ Migration failed:'));
+    console.error(chalk.red(error.message));
+    console.log(chalk.gray('\nYou can manually rename the folder:'));
+    console.log(chalk.cyan('  mv proagents .proagents\n'));
+  }
+}

package/lib/commands/status.js

@@ -7,7 +7,7 @@ import chalk from 'chalk';
  */
 export async function statusCommand() {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
 
   console.log('\n' + chalk.bold.blue('ProAgents Status'));
   console.log(chalk.blue('═'.repeat(40)) + '\n');

package/lib/commands/uninstall.js

@@ -24,7 +24,7 @@ const AI_FILES = [
  */
 export async function uninstallCommand(options = {}) {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
 
   console.log('\n' + chalk.bold.red('ProAgents Uninstall'));
   console.log(chalk.red('===================\n'));
@@ -45,7 +45,7 @@ export async function uninstallCommand(options = {}) {
     const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
 
     console.log(chalk.yellow('This will remove:'));
-    console.log(chalk.gray('  • ./proagents/ folder'));
+    console.log(chalk.gray('  • ./.proagents/ folder'));
     console.log(chalk.gray('  • AI instruction files (CLAUDE.md, .cursorrules, etc.)'));
     console.log(chalk.gray('  • ProAgents section from README.md\n'));
 
@@ -63,7 +63,7 @@ export async function uninstallCommand(options = {}) {
   // 1. Remove proagents folder
   if (existsSync(proagentsDir)) {
     rmSync(proagentsDir, { recursive: true, force: true });
-    console.log(chalk.green('✓ Removed ./proagents/ folder'));
+    console.log(chalk.green('✓ Removed ./.proagents/ folder'));
   }
 
   // 2. Remove AI instruction files from project root

package/lib/commands/upgrade.js

@@ -88,8 +88,8 @@ function getPackageVersion() {
  */
 export async function upgradeCommand(options = {}) {
   const targetDir = process.cwd();
-  const proagentsDir = join(targetDir, 'proagents');
-  const sourceDir = join(__dirname, '..', '..', 'proagents');
+  const proagentsDir = join(targetDir, '.proagents');
+  const sourceDir = join(__dirname, '..', '..', '.proagents');
 
   console.log(chalk.bold('\nProAgents Upgrade'));
   console.log(chalk.gray('=================\n'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proagents",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "AI-agnostic development workflow framework that automates the full software development lifecycle",
   "type": "module",
   "main": "lib/index.js",
@@ -14,7 +14,7 @@
   "files": [
     "bin/",
     "lib/",
-    "proagents/"
+    ".proagents/"
   ],
   "keywords": [
     "ai",