ai-scaffold-pro 1.1.1 → 2.0.1

package/README.md

@@ -0,0 +1,90 @@
+# ai-scaffold-pro
+
+> AI Coding Skeleton v2.0 — CLI + LLM Collaborative Architecture
+
+## Overview
+
+ai-scaffold-pro is a **CLI + LLM collaborative scaffolding system** that generates a complete AI coding assistance framework for your existing project.
+
+### Two-Phase Approach
+
+1. **CLI Phase** (10 seconds): Auto-detects your project type and creates the skeleton structure
+2. **AI Phase** (2-5 minutes): Scans your source code, understands architecture, and generates customized rules
+
+## Quick Start
+
+### Step 1: CLI Skeleton Creation
+
+```bash
+cd your-project/
+npx ai-scaffold-pro
+```
+
+Follow the minimal prompts:
+1. Select language (中文 / English)
+2. Select AI tool (Claude Code / Qoder / Codex / OpenCode)
+3. Project auto-detected
+4. Skeleton created!
+
+### Step 2: AI Deep Initialization
+
+Open your project in your chosen AI tool and enter:
+
+```
+Initialize using .qoder/skills/project_initialization/SKILL.md
+```
+
+The AI will automatically:
+- Scan your project structure
+- Read key source files
+- Ask 7-11 configuration questions
+- Generate customized rules based on actual code
+- Create comprehensive references documentation
+- Set up intelligent agents and hooks
+
+**Total time**: ~3 minutes (10s CLI + 2-5min AI)
+
+## Features
+
+- **CLI + LLM Collaboration**: CLI builds skeleton instantly, AI fills in customized content
+- **Multi-tool support**: Claude Code, Qoder, Codex, OpenCode
+- **Multi-platform**: Android, iOS, HarmonyOS, Flutter, React Native
+- **SKILL.md as AI Manual**: Comprehensive initialization guide
+- **Auto-generated references**: AI scans source code to generate accurate module docs
+- **CodeGraph integration**: Optional integration for better performance
+
+## Supported Platforms
+
+| Platform | Build System | Detection File |
+|----------|-------------|----------------|
+| Android | Gradle | `settings.gradle` / `build.gradle.kts` |
+| iOS | Xcode / SPM | `*.xcodeproj` / `Package.swift` |
+| HarmonyOS | Hvigor | `hvigor-config.json5` |
+| Flutter | Dart Pub | `pubspec.yaml` |
+| React Native | npm/yarn | `package.json` + react-native |
+| Generic | — | Fallback for any project |
+
+## Project Structure (After AI Initialization)
+
+```
+AGENTS.md / CLAUDE.md          ← Entry point (full version, generated by AI)
+AI_INIT_GUIDE.md               ← User-friendly initialization guide
+.qoder/ (or .claude/.codex/.opencode)
+├── CHANGELOG.md
+├── settings.json
+├── hooks/
+├── rules/                     ← AI-generated
+├── skills/
+│   └── project_initialization/ ← AI initialization manual
+├── agents/                    ← AI-generated
+├── scripts/
+└── references/                ← AI-generated from source code
+```
+
+## Repository
+
+For more information, visit: https://github.com/Jorgejie/ai_scaffold
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
 
 import chalk from 'chalk';
-import { execSync } from 'child_process';
 import { detectProject } from '../src/detect.js';
-import { promptConfig } from '../src/prompts.js';
-import { renderTemplates } from '../src/render.js';
+import { promptMinimalConfig } from '../src/prompts.js';
+import { createSkeleton } from '../src/render.js';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
@@ -12,75 +11,67 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATE_ROOT = path.resolve(__dirname, '../templates');
 
 async function main() {
-  console.log(chalk.cyan.bold('\n AI Coding Skeleton — ai-scaffold\n'));
+  console.log(chalk.cyan.bold('\n🤖 AI Coding Skeleton — ai-scaffold\n'));
+  console.log(chalk.gray('CLI + LLM 协作架构: CLI搭建骨架 → AI深度初始化\n'));
 
   const targetDir = process.argv[2] || process.cwd();
-  console.log(chalk.gray(` Target directory: ${targetDir}\n`));
+  console.log(chalk.gray(`📁 Target directory: ${targetDir}\n`));
 
-  // Phase 0: Language + AI tool selection
-  // Phase 1: Project detection
-  console.log(chalk.yellow(' Detecting project...'));
+  // Phase 1: 项目检测
+  console.log(chalk.yellow('🔍 Step 1: Detecting project...'));
   const detection = await detectProject(targetDir);
-  console.log(chalk.green(` Platform: ${detection.platform} / ${detection.buildSystem}`));
+  console.log(chalk.green(`✓ Platform: ${detection.platform} / ${detection.buildSystem}`));
+  console.log(chalk.green(`✓ Language: ${detection.language}`));
   if (detection.hasNdk) {
-    console.log(chalk.green(' NDK/C++: detected'));
+    console.log(chalk.green('✓ NDK/C++: detected'));
+  }
+  if (detection.hasCodeGraph) {
+    console.log(chalk.green('✓ CodeGraph: installed (will use lightweight mode)'));
   }
   console.log();
 
-  // Phase 0 + Phase 2: Interactive configuration
-  const config = await promptConfig(detection);
+  // Phase 2: 最小化配置（仅语言和AI工具选择）
+  console.log(chalk.yellow('⚙️  Step 2: Minimal configuration...'));
+  const config = await promptMinimalConfig(detection);
+  console.log(chalk.green(`✓ AI Tool: ${config.target}`));
+  console.log(chalk.green(`✓ Language: ${config.lang === 'zh' ? '中文' : 'English'}\n`));
 
-  // Phase 3: Generate files
-  console.log(chalk.yellow('\n Generating files...\n'));
-  await renderTemplates(TEMPLATE_ROOT, targetDir, config, detection);
+  // Phase 3: 创建骨架（不渲染具体内容）
+  console.log(chalk.yellow('🏗️  Step 3: Creating skeleton...'));
+  await createSkeleton(TEMPLATE_ROOT, targetDir, config, detection);
 
-  // Summary
+  // 输出完成信息和下一步指引
   const dir = config.dir;
   const entry = config.entry;
   const isZh = config.lang === 'zh';
-  const langLabel = config.lang === 'en' ? 'English' : '中文';
-  console.log(chalk.cyan.bold(`\n ${config.target.toUpperCase()} system initialized\n`));
-  console.log(chalk.white(` Language: ${langLabel}`));
-  console.log(chalk.white(` Entry file: ${entry}`));
-  console.log(chalk.white(` Config dir: ${dir}/`));
-
-  console.log('');
-  console.log(chalk.cyan(isZh ? '📋 下一步操作：' : '📋 Next Steps:'));
-  console.log('');
-  if (config.hasCodeGraph) {
-    console.log(chalk.white(isZh 
-      ? `  1. [必做] 运行 python ${dir}/scripts/gen_references.py --lightweight 生成轻量参考文档`
-      : `  1. [Required] Run python ${dir}/scripts/gen_references.py --lightweight to generate lightweight references`));
-  } else {
-    console.log(chalk.white(isZh 
-      ? `  1. [必做] 运行 python ${dir}/scripts/gen_references.py 生成项目参考文档`
-      : `  1. [Required] Run python ${dir}/scripts/gen_references.py to generate project references`));
-  }
-  console.log(chalk.white(isZh
-    ? `  2. [必做] 检查 ${dir}/rules/project_rule.md 中的架构约束是否符合项目实际`
-    : `  2. [Required] Review ${dir}/rules/project_rule.md to verify architecture constraints match your project`));
-  console.log(chalk.white(isZh
-    ? `  3. [可选] 调整 ${dir}/agents/ 中各 Agent 的检查规则`
-    : `  3. [Optional] Adjust check rules in ${dir}/agents/`));
-  console.log(chalk.white(isZh
-    ? `  4. [可选] 修改 ${dir}/skills/ 中的审查标准`
-    : `  4. [Optional] Modify review standards in ${dir}/skills/`));
-  console.log('');
+  
+  console.log(chalk.cyan.bold(`\n✅ Skeleton created successfully!\n`));
+  console.log(chalk.white(`Entry file: ${entry}`));
+  console.log(chalk.white(`Config dir: ${dir}/`));
+  console.log(chalk.white(`Language: ${isZh ? '中文' : 'English'}\n`));
+  
+  console.log(chalk.cyan.bold(isZh ? '📋 下一步操作：' : '📋 Next Steps:\n'));
+  console.log(chalk.white(isZh 
+    ? '  1. 在 AI 工具中打开本项目' 
+    : '  1. Open this project in your AI tool'));
+  console.log(chalk.white(isZh 
+    ? `  2. 输入指令: "按 ${dir}/skills/project_initialization/SKILL.md 初始化"`
+    : `  2. Enter command: "Initialize using ${dir}/skills/project_initialization/SKILL.md"`));
+  console.log(chalk.white(isZh 
+    ? '  3. AI 将扫描源码、理解架构、生成定制化规则'
+    : '  3. AI will scan source code, understand architecture, generate customized rules'));
+  console.log();
+  
+  console.log(chalk.gray(isZh 
+    ? '  💡 提示: 查看 AI_INIT_GUIDE.md 了解详细流程'
+    : '  💡 Tip: See AI_INIT_GUIDE.md for detailed instructions'));
   console.log(chalk.gray(isZh 
-    ? '  预计补充时间：5-10 分钟'
-    : '  Estimated setup time: 5-10 minutes'));
-  console.log(chalk.gray(isZh
-    ? '  验证方式：让 AI 阅读生成的规则文件并确认无冲突'
-    : '  Verification: Ask the AI to read the generated rules and confirm no conflicts'));
-  console.log('');
+    ? '  ⏱️  预计AI初始化时间: 2-5分钟\n'
+    : '  ⏱️  Estimated AI initialization time: 2-5 minutes\n'));
 }
 
 main().catch(err => {
-  console.error(chalk.red('Error:'), err.message);
-  process.exit(1);
-});
-
-main().catch(err => {
-  console.error(chalk.red('Error:'), err.message);
+  console.error(chalk.red('\n❌ Error:'), err.message);
+  console.error(chalk.red('   No files were written to the target directory.'));
   process.exit(1);
 });

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "ai-scaffold-pro",
-  "version": "1.1.1",
-  "description": "AI Coding Skeleton — Generate structured rules, skills, agents, and hooks for your project",
+  "version": "2.0.1",
+  "description": "AI Coding Skeleton — CLI + LLM协作架构: CLI搭建骨架 → AI深度初始化",
   "bin": {
-    "ai-scaffold-pro": "./bin/cli.js"
+    "ai-scaffold-pro": "bin/cli.js"
   },
   "type": "module",
   "scripts": {
-    "start": "node bin/cli.js"
+    "start": "node bin/cli.js",
+    "bootstrap": "bash scripts/bootstrap.sh"
   },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "hooks/",
+    "scripts/",
+    "i18n/",
+    "package.json",
+    "README.md"
+  ],
   "keywords": [
     "ai",
     "coding",
@@ -18,7 +29,8 @@
     "codex",
     "opencode",
     "rules",
-    "scaffold"
+    "scaffold",
+    "cli-llm-collaboration"
   ],
   "license": "MIT",
   "dependencies": {

package/scripts/bootstrap.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# ai-scaffold 快速启动脚本
+# 一键执行: CLI骨架搭建 + AI初始化指引
+
+set -e
+
+echo "🤖 AI Coding Skeleton — ai-scaffold"
+echo "===================================="
+echo ""
+
+# 检查是否在Git仓库中
+if [ ! -d ".git" ]; then
+    echo "⚠️  Warning: Current directory is not a Git repository."
+    echo "   It's recommended to initialize Git first:"
+    echo "   git init"
+    echo ""
+fi
+
+# Step 1: 运行CLI创建骨架
+echo "🔧 Step 1: Creating project skeleton..."
+echo ""
+
+npx ai-scaffold-pro "$@"
+
+echo ""
+echo "===================================="
+echo ""
+
+# Step 2: 显示AI初始化指引
+echo "🤖 Step 2: AI Initialization Guide"
+echo ""
+echo "✅ Skeleton created successfully!"
+echo ""
+echo "Next steps:"
+echo ""
+echo "1. Open this project in your AI coding assistant:"
+echo "   - Claude Code"
+echo "   - Qoder"  
+echo "   - Codex"
+echo "   - OpenCode"
+echo ""
+echo "2. In the AI chat, enter one of these commands:"
+echo ""
+echo "   Option A:"
+echo "   👉 '按 .qoder/skills/project_initialization/SKILL.md 初始化'"
+echo ""
+echo "   Option B:"
+echo "   👉 '阅读 AI_INIT_GUIDE.md 并执行初始化'"
+echo ""
+echo "3. The AI will:"
+echo "   • Scan your source code"
+echo "   • Understand your project architecture"
+echo "   • Generate customized rules based on actual code"
+echo "   • Create comprehensive references documentation"
+echo "   • Set up intelligent agents and hooks"
+echo ""
+echo "   Estimated time: 2-5 minutes"
+echo ""
+echo "💡 Tip: See AI_INIT_GUIDE.md for detailed instructions"
+echo ""
+echo "===================================="
+echo ""
+echo "Happy coding! 🎉"

package/src/detect.js

@@ -39,10 +39,13 @@ export async function detectProject(targetDir) {
     allDetected: [],
   };
 
+  console.log(chalk.gray('  Scanning project structure...'));
+
   // 1. 检测已有 AI 工具
   for (const [indicator, tool] of Object.entries(AI_TOOLS)) {
     if (fs.existsSync(path.join(targetDir, indicator))) {
       result.existingTool = tool;
+      console.log(chalk.gray(`  ✓ Found existing ${tool.target} setup (${indicator})`));
       break;
     }
   }
@@ -60,11 +63,13 @@ export async function detectProject(targetDir) {
 
   // 输出检测日志
   if (matched.length > 0) {
-    console.log(chalk.gray('  检测到以下项目指标:'));
+    console.log(chalk.gray('  Detected project indicators:'));
     for (const m of matched) {
       const label = m.platform || 'package.json';
       console.log(chalk.gray(`    • ${m.file} → ${label} (priority: ${m.priority})`));
     }
+  } else {
+    console.log(chalk.yellow('  ⚠ No standard project indicators found, using generic mode'));
   }
 
   // 3. 确定平台
@@ -77,15 +82,18 @@ export async function detectProject(targetDir) {
       if (isAndroid) {
         result.platform = 'Android';
         result.buildSystem = top.build;
+        console.log(chalk.gray('  ✓ Verified as Android project (found AndroidManifest.xml or com.android plugin)'));
       } else {
         result.platform = 'JVM';
         result.buildSystem = top.build;
+        console.log(chalk.gray('  ✓ Detected as JVM project (no Android-specific files)'));
       }
     } else if (top.platform === null && top.file === 'package.json') {
       // package.json 深度检测
       const detected = detectFromPackageJson(targetDir);
       result.platform = detected.platform;
       result.buildSystem = detected.build;
+      console.log(chalk.gray(`  ✓ Identified Node.js project type: ${detected.platform}`));
     } else {
       result.platform = top.platform;
       result.buildSystem = top.build;
@@ -100,22 +108,32 @@ export async function detectProject(targetDir) {
 
     // 混合项目日志
     if (matched.length > 1) {
-      console.log(chalk.yellow(`  ⚠ 检测到多个平台指标，已选择最高优先级: ${result.platform} (${result.buildSystem})`));
+      console.log(chalk.yellow(`  ⚠ Multiple platforms detected, selected highest priority: ${result.platform} (${result.buildSystem})`));
+      console.log(chalk.gray(`    Other detected platforms: ${matched.slice(1).map(m => m.platform || 'Node').join(', ')}`));
     }
   }
 
   // 4. 检测 NDK/C++
   result.hasNdk = detectNdk(targetDir);
+  if (result.hasNdk) {
+    console.log(chalk.gray('  ✓ NDK/C++ code detected (found .cpp/.c/.h files or CMakeLists.txt)'));
+  }
 
   // 5. 检测语言
   result.language = detectLanguage(targetDir, result.platform, result.buildSystem);
+  console.log(chalk.gray(`  ✓ Primary language: ${result.language}`));
 
   // 6. 检测 CodeGraph
   result.hasCodeGraph = detectCodeGraph();
   if (result.hasCodeGraph) {
-    console.log(chalk.gray('  CodeGraph: detected'));
+    console.log(chalk.gray('  ✓ CodeGraph CLI detected (will use lightweight references mode)'));
+  } else {
+    console.log(chalk.gray('  ℹ CodeGraph CLI not found (will use full references mode)'));
+    console.log(chalk.gray('    Tip: Install with `npx @colbymchenry/codegraph` for better performance'));
   }
 
+  console.log(chalk.green(`\n  Project detection complete: ${result.platform} / ${result.buildSystem}\n`));
+
   return result;
 }
 

package/src/prompts.js

@@ -1,6 +1,10 @@
 import inquirer from 'inquirer';
 
-export async function promptConfig(detection) {
+/**
+ * 最小化配置 - 仅收集语言和AI工具选择
+ * 其他所有配置将由AI在初始化时通过交互式问答收集
+ */
+export async function promptMinimalConfig(detection) {
   const answers = {};
 
   // Phase 0: Language selection
@@ -59,133 +63,22 @@ export async function promptConfig(detection) {
     answers.entry = 'AGENTS.md';
   }
 
-  // Phase 1.5: CodeGraph detection and prompt
-  if (detection.hasCodeGraph) {
-    answers.hasCodeGraph = true;
-  } else {
-    const { installCodeGraph } = await inquirer.prompt([
-      {
-        type: 'confirm',
-        name: 'installCodeGraph',
-        message: isZh
-          ? '检测到项目未安装 CodeGraph（代码关系图工具，可提升 AI 对代码库的理解能力）。是否安装？'
-          : 'CodeGraph (code relationship graph tool for improved AI codebase understanding) is not installed. Install it?',
-        default: true,
-      },
-    ]);
-    answers.installCodeGraph = installCodeGraph;
-    answers.hasCodeGraph = false;
-  }
-
-  // Phase 2: Configuration questions
-  const configPrompts = [
-    {
-      type: 'input',
-      name: 'projectName',
-      message: isZh ? '项目名称' : 'Project name',
-      default: 'MyProject',
-      validate: v => {
-        if (!v || v.trim().length === 0) {
-          return isZh ? '项目名不能为空' : 'Project name cannot be empty';
-        }
-        if (v.length > 50) {
-          return isZh ? '项目名不能超过 50 个字符' : 'Project name cannot exceed 50 characters';
-        }
-        return true;
-      },
-    },
-    {
-      type: 'input',
-      name: 'projectDescription',
-      message: isZh ? '项目描述（一句话）' : 'Project description (one sentence)',
-      default: isZh ? '一个项目' : 'A project',
-    },
-    {
-      type: 'input',
-      name: 'packageName',
-      message: isZh ? '主包名' : 'Main package name',
-      default: 'com.example.app',
-      validate: v => {
-        if (!v) return true;
-        if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(v)) {
-          return isZh ? '请输入有效的包名格式 (如 com.example.app)' : 'Please enter a valid package name (e.g. com.example.app)';
-        }
-        return true;
-      },
-    },
-    {
-      type: 'input',
-      name: 'aiName',
-      message: isZh ? 'AI 助手名称' : 'AI assistant name',
-      default: 'AI Assistant',
-    },
-    {
-      type: 'input',
-      name: 'buildDebug',
-      message: isZh ? 'Debug 构建命令' : 'Debug build command',
-      default: detection.platform === 'Android' ? './gradlew assembleDebug' : 'npm run build',
-    },
-    {
-      type: 'input',
-      name: 'buildRelease',
-      message: isZh ? 'Release 构建命令' : 'Release build command',
-      default: detection.platform === 'Android' ? './gradlew assembleRelease' : 'npm run build:prod',
-    },
-    {
-      type: 'confirm',
-      name: 'hasTests',
-      message: isZh ? '项目有自动化测试吗？' : 'Does the project have automated tests?',
-      default: true,
-    },
-    {
-      type: 'input',
-      name: 'reviewThreshold',
-      message: isZh ? '修改几个文件触发代码审查？' : 'How many files modified triggers code review?',
-      default: '2',
-      validate: v => {
-        const n = parseInt(v);
-        if (isNaN(n) || n < 1 || n > 100) {
-          return isZh ? '请输入 1-100 之间的数字' : 'Please enter a number between 1 and 100';
-        }
-        return true;
-      },
-      filter: v => parseInt(v),
-    },
-    {
-      type: 'input',
-      name: 'archThreshold',
-      message: isZh ? '修改几个模块触发架构审查？' : 'How many modules modified triggers architecture review?',
-      default: '3',
-      validate: v => !isNaN(v) || 'Please enter a number',
-    },
-  ];
-
-  const config = await inquirer.prompt(configPrompts);
-  Object.assign(answers, config);
-
-  // NDK questions
-  if (detection.hasNdk) {
-    const ndkConfig = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'ndkBuildSystem',
-        message: isZh ? 'NDK 构建系统' : 'NDK build system',
-        choices: ['ndk-build', 'CMake'],
-        default: 'ndk-build',
-      },
-      {
-        type: 'list',
-        name: 'jniMethod',
-        message: isZh ? 'JNI native 方法注册方式' : 'JNI native method registration',
-        choices: [
-          { name: isZh ? '动态注册 (RegisterNatives)' : 'Dynamic (RegisterNatives)', value: 'dynamic' },
-          { name: isZh ? '静态绑定' : 'Static binding', value: 'static' },
-        ],
-        default: 'dynamic',
-      },
-    ]);
-    Object.assign(answers, ndkConfig);
-  }
+  // 设置显示名称
+  answers.targetDisplay = {
+    'claude': 'Claude Code',
+    'qoder': 'Qoder',
+    'codex': 'Codex',
+    'opencode': 'OpenCode'
+  }[answers.target];
 
   return answers;
 }
+
+/**
+ * 原有的完整配置函数（已废弃，保留供参考）
+ * @deprecated 使用 promptMinimalConfig 代替
+ */
+export async function promptConfig(detection) {
+  console.warn('⚠️  Warning: promptConfig is deprecated, use promptMinimalConfig instead');
+  return await promptMinimalConfig(detection);
+}