Fix critical bugs and improve framework quality

This commit addresses 9 critical and major issues identified in comprehensive code review:

CRITICAL FIXES:
- Remove all 'agentcodex start' references → 'agentcodex init' (17 files)
  Clarified workflow: init creates structure, /agentcodex-start builds in Claude Code
- Fix package.json: Remove invalid 'main' field, add .agentcodex-version to files array
- Fix slash command: Update paths (./docs/ideation → ./ideation), agent count (21→23)
- Remove jest: No tests exist, added placeholder for v2.4.0
- Update agent count: 21 → 23 agents globally (14 files + CLI output)
- Fix broken documentation links: 5 links updated to correct paths
- **NEW BUG FOUND:** Add .agentcodex-version copy to projects (sync system requirement)

MAJOR IMPROVEMENTS:
- Add comprehensive error recovery/cleanup to cmdInit()
  * Cleanup partial projects on failure
  * Contextual error messages (EEXIST, EACCES, etc.)
- Add dependency checks: git, node 18+ validated before init
- Document ORACLE as v2.5.0+ specification (not yet implemented)
- Document template variables as v2.4.0+ feature (planned)
- Create GitHub Actions setup documentation (688 lines)
- Add copyVersionFile() function for sync system compatibility

FILES MODIFIED: 27
- 7 agent/command files
- 17 documentation files
- 2 CLI files (agentcodex, project-init.js)
- 1 package.json

TESTING:
- Tested agentcodex init: Creates 23 agents, 4 workflows, all files ✓
- Tested sync system: Version tracking working ✓
- Verified dependency checks: git + node validation ✓

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: AssistantCompany

.claude/agents/maestro.md

@@ -640,7 +640,11 @@ Spawn ORACLE with:
 
 ```
 $ cd /home/dev/CODE/my-new-app
-$ agentcodex start
+$ agentcodex init
+# (Creates project structure)
+
+$ claude code
+# In Claude Code, run: /agentcodex-start
 
 MAESTRO: Starting AgentCodeX...
 MAESTRO: Initializing project context...

.claude/agents/oracle.md

@@ -7,6 +7,25 @@ model: sonnet
 
 # ORACLE - Self-Improving Meta-Learner
 
+> ⚠️ **SPECIFICATION FOR FUTURE IMPLEMENTATION**
+>
+> This agent defines the vision for AgentCodeX's self-improving system (planned for v2.5.0+).
+>
+> **Current v2.3.0 status:**
+> - ORACLE agent definition exists (this file)
+> - No automatic metric collection implemented yet
+> - No self-learning system active
+>
+> **Planned for v2.5.0+:**
+> - Automated project metrics collection
+> - Agent performance tracking
+> - Self-optimization of agent prompts
+> - Automatic version upgrades based on improvements
+>
+> For now, this serves as the specification that will guide ORACLE's development.
+
+---
+
 You are **ORACLE**, the self-improving consciousness of AgentCodeX.
 
 ## CORE MISSION

.claude/commands/agentcodex-start.md

@@ -2,13 +2,13 @@
 description: Launch MAESTRO to build complete AgentCodeX project from ideation
 ---
 
-Launch the MAESTRO agent to initialize and build a complete AgentCodeX project from the ./docs/ideation/ folder.
+Launch the MAESTRO agent to initialize and build a complete AgentCodeX project from the ./ideation/ folder.
 
 ## What MAESTRO Will Do
 
-MAESTRO will autonomously orchestrate all 21 specialized agents to:
+MAESTRO will autonomously orchestrate all 23 specialized agents to:
 
-1. **Review Ideation** - Read all files in ./docs/ideation/
+1. **Review Ideation** - Read all files in ./ideation/
 2. **Create PRD** - Spawn VISIONARY to create comprehensive Product Requirements Document
 3. **Design Architecture** - Spawn ARCHITECT to design complete system architecture
 4. **Build Backend** - Spawn FORGE to create FastAPI backend with GPT-5 integration
@@ -64,7 +64,7 @@ Then MAESTRO will take over and build your entire application autonomously.
 
 ## Notes
 
-- Ensure ./docs/ideation/ folder exists with prd.md at minimum
+- Ensure ./ideation/ folder exists with prd.md at minimum
 - MAESTRO only asks for information it cannot determine itself
 - All agents work autonomously - you just provide feedback
 - ORACLE will learn from this project to improve future builds

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Be respectful, inclusive, and collaborative. We're building the future of agenti
 
 ### 1. Improve Agent Prompts
 
-The heart of AgentCodeX is the 21 specialized agents. Making them smarter benefits everyone.
+The heart of AgentCodeX is the 23 specialized agents. Making them smarter benefits everyone.
 
 **Where:** `.claude/agents/*.md`
 
@@ -130,7 +130,7 @@ agentcodex --version
 
 # Test locally
 cd /tmp/test-project
-agentcodex start
+agentcodex init
 ```
 
 **Test agent changes:**
@@ -151,7 +151,7 @@ mkdir -p /tmp/test-project/ideation
 
 # Create test project and verify files are generated correctly
 mkdir test && cd test
-agentcodex start
+agentcodex init
 ```
 
 ## Pull Request Process

cli/agentcodex

@@ -21,6 +21,7 @@ const {
   copyAgents,
   copyCommands,
   copyWorkflows,
+  copyVersionFile,
   createClaudeJson,
   createStarterPRD,
   createGitignore,
@@ -88,10 +89,78 @@ ${colors.green}Report issues:${colors.reset}
   `);
 }
 
+/**
+ * Check system dependencies
+ * @returns {object} - Status of required dependencies
+ */
+function checkDependencies() {
+  const checks = {
+    node: { installed: false, version: null, min: '18.0.0' },
+    git: { installed: false, version: null },
+  };
+
+  // Check Node.js
+  try {
+    const nodeVersion = process.version.slice(1); // Remove 'v' prefix
+    checks.node.installed = true;
+    checks.node.version = nodeVersion;
+
+    const [major] = nodeVersion.split('.').map(Number);
+    const [minMajor] = checks.node.min.split('.').map(Number);
+    checks.node.meetsRequirement = major >= minMajor;
+  } catch (error) {
+    checks.node.installed = false;
+  }
+
+  // Check Git
+  try {
+    const gitVersion = execSync('git --version', { encoding: 'utf-8' }).trim();
+    checks.git.installed = true;
+    checks.git.version = gitVersion.replace('git version ', '');
+    checks.git.meetsRequirement = true;
+  } catch (error) {
+    checks.git.installed = false;
+  }
+
+  return checks;
+}
+
 async function cmdInit(options = {}) {
   printBanner();
   console.log(`${colors.bright}Initializing New AgentCodeX Project${colors.reset}\n`);
 
+  // Check dependencies first
+  console.log(`${colors.cyan}Checking system dependencies...${colors.reset}\n`);
+  const deps = checkDependencies();
+
+  let hasErrors = false;
+
+  // Node.js check
+  if (!deps.node.installed) {
+    console.error(`${colors.red}✗ Node.js not found${colors.reset}`);
+    hasErrors = true;
+  } else if (!deps.node.meetsRequirement) {
+    console.error(`${colors.red}✗ Node.js ${deps.node.version} (requires ${deps.node.min}+)${colors.reset}`);
+    hasErrors = true;
+  } else {
+    console.log(`${colors.green}✓ Node.js ${deps.node.version}${colors.reset}`);
+  }
+
+  // Git check
+  if (!deps.git.installed) {
+    console.error(`${colors.red}✗ Git not found${colors.reset}`);
+    hasErrors = true;
+  } else {
+    console.log(`${colors.green}✓ Git ${deps.git.version}${colors.reset}`);
+  }
+
+  if (hasErrors) {
+    console.error(`\n${colors.red}Missing required dependencies. Please install and try again.${colors.reset}\n`);
+    process.exit(1);
+  }
+
+  console.log('');
+
   // Use CLI flags if provided, otherwise prompt
   let PROJECT_NAME, DEV_URL, PROD_URL;
 
@@ -122,10 +191,14 @@ async function cmdInit(options = {}) {
 
   console.log(`\n${colors.cyan}Creating project structure...${colors.reset}\n`);
 
+  // Track project root for cleanup on failure
+  let projectRoot = null;
+
   try {
     // Initialize project structure (use current directory)
     const baseDir = options.baseDir || process.cwd();
     const projectInfo = initializeProject(PROJECT_NAME, DEV_URL, PROD_URL, baseDir);
+    projectRoot = projectInfo.projectRoot;
 
     // Get source directories
     const frameworkRoot = path.join(__dirname, '..');
@@ -146,6 +219,10 @@ async function cmdInit(options = {}) {
     const targetWorkflowsDir = path.join(projectInfo.projectRoot, '.github', 'workflows');
     copyWorkflows(sourceWorkflowsDir, targetWorkflowsDir);
 
+    // Copy framework version file (CRITICAL for sync system)
+    console.log(`${colors.cyan}Copying framework version file...${colors.reset}`);
+    copyVersionFile(frameworkRoot, projectInfo.projectRoot);
+
     // Create claude.json (REQUIRED for slash commands to work)
     console.log(`${colors.cyan}Creating .claude/claude.json...${colors.reset}`);
     createClaudeJson(path.join(projectInfo.projectRoot, '.claude'));
@@ -245,7 +322,7 @@ async function cmdInit(options = {}) {
     console.log(`${colors.bright}What MAESTRO Will Do:${colors.reset}`);
     console.log(`  • Read your PRD from docs/ideation/`);
     console.log(`  • Ask for OpenAI API key and any other credentials`);
-    console.log(`  • Orchestrate 21 specialized agents`);
+    console.log(`  • Orchestrate 23 specialized agents`);
     console.log(`  • Build complete application (~45 minutes)`);
     console.log(`  • Deploy to ${DEV_URL}\n`);
 
@@ -256,6 +333,35 @@ async function cmdInit(options = {}) {
 
   } catch (error) {
     console.error(`\n${colors.red}✗ Error creating project: ${error.message}${colors.reset}\n`);
+
+    // Cleanup: Remove partially created project directory
+    if (projectRoot && fs.existsSync(projectRoot)) {
+      console.log(`${colors.yellow}Cleaning up partial project...${colors.reset}`);
+      try {
+        fs.rmSync(projectRoot, { recursive: true, force: true });
+        console.log(`${colors.green}✓ Cleanup complete${colors.reset}\n`);
+      } catch (cleanupError) {
+        console.error(`${colors.red}⚠ Failed to clean up ${projectRoot}${colors.reset}`);
+        console.error(`${colors.yellow}Please remove it manually.${colors.reset}\n`);
+      }
+    }
+
+    // Provide helpful error context
+    console.log(`${colors.bright}Troubleshooting:${colors.reset}`);
+    if (error.message.includes('EEXIST')) {
+      console.log(`  • Project "${PROJECT_NAME}" already exists`);
+      console.log(`  • Choose a different name or remove existing project\n`);
+    } else if (error.message.includes('EACCES') || error.message.includes('EPERM')) {
+      console.log(`  • Permission denied - check directory write permissions`);
+      console.log(`  • Try running with appropriate permissions\n`);
+    } else if (error.message.includes('not found')) {
+      console.log(`  • Framework files missing - reinstall AgentCodeX`);
+      console.log(`  • Run: npm install -g agentcodex\n`);
+    } else {
+      console.log(`  • Check framework installation: npm list -g agentcodex`);
+      console.log(`  • Report issue: https://github.com/ScaledMinds/AgentCodeX/issues\n`);
+    }
+
     process.exit(1);
   }
 }

cli/lib/project-init.js

@@ -382,7 +382,7 @@ function createClaudeMd(projectRoot, projectName, devUrl, prodUrl) {
 **This IS:**
 - ✅ A user project generated BY AgentCodeX
 - ✅ Where you will create application code
-- ✅ Where all 21 agents will build the actual application
+- ✅ Where all 23 agents will build the actual application
 
 ### Project Structure
 
@@ -409,15 +409,15 @@ ${projectName}/
 ### Phase 1: YOU ARE HERE - Setup ✅
 
 1. ✅ Project initialized with \`agentcodex init\`
-2. ✅ All 21 agents copied locally
+2. ✅ All 23 agents copied locally
 3. ✅ PRD template created at \`docs/ideation/prd.md\`
 4. **NEXT:** Human edits the PRD with their requirements
 
 ### Phase 2: MAESTRO Build (Not Started Yet)
 
 1. Human runs \`/agentcodex-start\` in Claude Code
 2. MAESTRO agent activates and reads \`docs/ideation/prd.md\`
-3. MAESTRO orchestrates all 21 agents to build:
+3. MAESTRO orchestrates all 23 agents to build:
    - Complete backend (FastAPI + GPT-5)
    - Complete frontend (Next.js + React)
    - Database schemas (PostgreSQL + Weaviate)
@@ -435,7 +435,7 @@ MAESTRO deploys to:
 
 ---
 
-## The 21 Agents Available
+## The 23 Agents Available
 
 All agents are in \`.claude/agents/\` - these are LOCAL COPIES for THIS project:
 
@@ -563,7 +563,7 @@ Everything else is fully autonomous.
    - All your work goes in THIS directory
 
 2. **Agents are local copies**
-   - The 21 agents in \`.claude/agents/\` are YOUR copies
+   - The 23 agents in \`.claude/agents/\` are YOUR copies
    - They will build YOUR application code here
    - They won't touch the framework
 
@@ -573,7 +573,7 @@ Everything else is fully autonomous.
    - MAESTRO takes over from there
 
 4. **Trust the process**
-   - MAESTRO coordinates all 21 agents
+   - MAESTRO coordinates all 23 agents
    - Each agent knows its role
    - The system is fully tested (1,000+ scenarios, 0 failures)
 
@@ -666,11 +666,30 @@ function copyWorkflows(sourceWorkflowsDir, targetWorkflowsDir) {
   return workflowFiles.length;
 }
 
+/**
+ * Copy framework version file to project
+ * CRITICAL: This file is required for sync system to track framework version
+ * @param {string} frameworkRoot - Framework root directory
+ * @param {string} projectRoot - Project root directory
+ */
+function copyVersionFile(frameworkRoot, projectRoot) {
+  const sourceVersionFile = path.join(frameworkRoot, '.agentcodex-version');
+  const targetVersionFile = path.join(projectRoot, '.agentcodex-version');
+
+  if (!fs.existsSync(sourceVersionFile)) {
+    throw new Error('Framework .agentcodex-version file not found');
+  }
+
+  fs.copyFileSync(sourceVersionFile, targetVersionFile);
+  console.log(`✓ Copied .agentcodex-version`);
+}
+
 module.exports = {
   initializeProject,
   copyAgents,
   copyCommands,
   copyWorkflows,
+  copyVersionFile,
   createClaudeJson,
   createStarterPRD,
   createGitignore,

docs/about/WHAT-IS-AGENTCODEX.md

@@ -354,7 +354,7 @@ NOT on:
 - **Deep Dive:** Read [Framework Overview](FRAMEWORK-OVERVIEW.md)
 - **Understand Workflow:** See [Workflow Explained](WORKFLOW-EXPLAINED.md)
 - **Explore Use Cases:** Check [Use Cases](USE-CASES.md)
-- **Get Started:** Follow our [Installation Guide](../getting-started/installation.md)
+- **Get Started:** Follow our [Installation Guide](../getting-started/quick-start.md)
 
 ---
 

docs/about/WORKFLOW-EXPLAINED.md

@@ -942,7 +942,7 @@ MAESTRO verifies:
 
 - **Understand Agents:** See [Agent Orchestration](AGENT-ORCHESTRATION.md)
 - **Explore Architecture:** Read [System Architecture](ARCHITECTURE.md)
-- **Try It:** Follow [Getting Started](../getting-started/installation.md)
+- **Try It:** Follow [Getting Started](../getting-started/quick-start.md)
 
 ---
 

docs/agents/README.md

@@ -139,4 +139,4 @@ MAESTRO: Use MY-CUSTOM-AGENT to handle task X
 
 [TO BE COMPLETED: Individual agent specification files]
 
-For now, see complete agent specs in [AGENTCODEX-MASTERPLAN.md](../../AGENTCODEX-MASTERPLAN.md)
+For now, see complete agent specs in [AGENTCODEX-MASTERPLAN.md](../README.md)

docs/getting-started/quick-start-simple.md

@@ -35,7 +35,7 @@ We're building an AI-powered customer support platform.
 ## Run AgentCodeX
 
 ```bash
-agentcodex start
+agentcodex init
 ```
 
 This will: