ac-framework 1.9.1 → 1.9.3

package/src/commands/init.js

@@ -17,17 +17,27 @@ import inquirer from 'inquirer';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { DESCRIPTIONS, ASSISTANT_ICONS, BUNDLED } from '../config/constants.js';
+import {
+  DESCRIPTIONS,
+  ASSISTANT_ICONS,
+  BUNDLED,
+  TEMPLATE_DESCRIPTIONS,
+  TEMPLATE_CAPABILITIES,
+  TEMPLATE_SKILL_PREVIEWS,
+} from '../config/constants.js';
 import { IDE_MD_MAP, AVAILABLE_MD_FILES, MD_DESCRIPTIONS } from '../config/ide-mapping.js';
-import { formatFolderName, sleep } from '../utils/helpers.js';
+import { formatFolderName, formatTemplateName, sleep } from '../utils/helpers.js';
 import { detectIDE } from '../services/detector.js';
 import {
+  getAvailableTemplates,
   getSelectableModules,
+  resolveTemplatePath,
   expandWithBundled,
   existsInTarget,
   copyModule,
   copyMdFile,
   FRAMEWORK_PATH,
+  saveTemplateSelection,
 } from '../services/installer.js';
 import { downloadWithSpinner, cleanupTempDir } from '../services/github-sync.js';
 import {
@@ -167,6 +177,40 @@ function buildChoices(folders) {
   return choices;
 }
 
+function buildTemplateChoices(templates) {
+  return templates.map((template) => {
+    const displayName = formatTemplateName(template);
+    const desc = TEMPLATE_DESCRIPTIONS[template] || 'Template for AI-assisted development workflows';
+    return {
+      name:
+        `${chalk.hex('#DFE6E9').bold(displayName)}` +
+        chalk.hex('#636E72')(` · ${desc}`),
+      value: template,
+      short: displayName,
+    };
+  });
+}
+
+function printTemplatePreview(template) {
+  const capabilities = TEMPLATE_CAPABILITIES[template] || [];
+  const skills = TEMPLATE_SKILL_PREVIEWS[template] || [];
+
+  if (capabilities.length > 0) {
+    console.log(chalk.hex('#B2BEC3')('  What this template is optimized for:'));
+    for (const item of capabilities) {
+      console.log(chalk.hex('#00CEC9')('  ◆ ') + chalk.hex('#DFE6E9')(item));
+    }
+    console.log();
+  }
+
+  if (skills.length > 0) {
+    console.log(chalk.hex('#B2BEC3')('  Included skill examples:'));
+    const skillLine = skills.map((skill) => `\`${skill}\``).join('  ');
+    console.log(chalk.hex('#6C5CE7')(`  ${skillLine}`));
+    console.log();
+  }
+}
+
 /**
  * Given the user's selected modules, determine which unique .md files
  * are needed. Returns a de-duplicated sorted array.
@@ -297,62 +341,71 @@ export async function initCommand(options = {}) {
     console.log();
     await pulseDiamondIntro(1800);
     
-    // ── Download (only with --latest / --branch) ──────────────────
-    if (useLatest) {
-      await stepHeader(1, totalSteps, 'Downloading latest framework');
-
-      const branchLabel = options.branch || 'main';
-      const branchBadge = chalk.hex('#2D3436').bgHex('#6C5CE7').bold(` ${branchLabel} `);
-      console.log(`  ${chalk.hex('#636E72')('Branch:')} ${branchBadge}`);
-      console.log();
+    // ── Step: Scan ────────────────────────────────────────────────
+    await stepHeader(1, totalSteps, 'Scanning framework templates');
+    await scanAnimation('Indexing available templates', 1000);
+    console.log();
 
-      try {
-        const result = await downloadWithSpinner({
-          branch: options.branch,
-        });
-        tempDir = result.tempDir;
-        frameworkPath = result.tempDir;
+    let templates;
+    try {
+      templates = await getAvailableTemplates(frameworkPath);
+    } catch {
+      console.log(chalk.hex('#D63031')('  ✗ Error: Could not read framework directory.'));
+      console.log(chalk.hex('#636E72')('  Make sure ac-framework is installed correctly.'));
+      process.exit(1);
+    }
 
-        if (result.commitSha) {
-          const shaBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${result.commitSha.slice(0, 7)} `);
-          console.log(`  ${shaBadge} ${chalk.hex('#636E72')('latest commit')}`);
-        }
-        console.log();
-      } catch (err) {
-        console.log();
-        console.log(chalk.hex('#FDCB6E')(`  ⚠  ${err.message}`));
-        console.log(chalk.hex('#636E72')('  Falling back to bundled version...\n'));
-        frameworkPath = FRAMEWORK_PATH;
-      }
+    if (templates.length === 0) {
+      console.log(chalk.hex('#FDCB6E')('  No templates found in framework directory.'));
+      process.exit(0);
     }
 
-    // ── Step: Scan ────────────────────────────────────────────────
-    await stepHeader(1 + stepOffset, totalSteps, 'Scanning framework modules');
-    await scanAnimation('Indexing available modules', 1000);
+    const countBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${templates.length} `);
+    console.log(`  ${countBadge} ${chalk.hex('#B2BEC3')('templates found')}`);
+    console.log();
+    await animatedSeparator(60);
     console.log();
 
+    // ── Step: Select Template ─────────────────────────────────────
+    await stepHeader(2, totalSteps, 'Select your template');
+
+    const templateChoices = buildTemplateChoices(templates);
+    const { template } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'template',
+        message: acGradient('Choose a development template:'),
+        choices: templateChoices,
+        pageSize: 10,
+      },
+    ]);
+
+    const localTemplatePath = await resolveTemplatePath(template, frameworkPath);
+    const templateBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${formatTemplateName(template)} `);
+    console.log();
+    console.log(`  ${chalk.hex('#636E72')('Template:')} ${templateBadge}`);
+    console.log(chalk.hex('#636E72')(`  Source: ${useLatest ? 'GitHub (Pending)' : localTemplatePath}`));
+    console.log();
+    printTemplatePreview(template);
+
     let folders;
     try {
-      folders = await getSelectableModules(frameworkPath);
+      folders = await getSelectableModules(localTemplatePath);
     } catch {
-      console.log(chalk.hex('#D63031')('  ✗ Error: Could not read framework directory.'));
-      console.log(chalk.hex('#636E72')('  Make sure ac-framework is installed correctly.'));
+      console.log(chalk.hex('#D63031')('  ✗ Error: Could not read template contents.'));
       process.exit(1);
     }
 
     if (folders.length === 0) {
-      console.log(chalk.hex('#FDCB6E')('  No modules found in framework directory.'));
+      console.log(chalk.hex('#FDCB6E')('  No assistant modules found inside the selected template.'));
       process.exit(0);
     }
 
-    const countBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${folders.length} `);
-    console.log(`  ${countBadge} ${chalk.hex('#B2BEC3')('assistant modules found')}`);
-    console.log();
     await animatedSeparator(60);
     console.log();
 
     // ── Step: Select ──────────────────────────────────────────────
-    await stepHeader(2 + stepOffset, totalSteps, 'Select your assistants');
+    await stepHeader(3, totalSteps, 'Select your assistants');
 
     const key = (k) => chalk.hex('#2D3436').bgHex('#636E72')(` ${k} `);
     console.log(
@@ -451,7 +504,7 @@ export async function initCommand(options = {}) {
     // ── Step: Instruction Files ───────────────────────────────────
     await animatedSeparator(60);
     console.log();
-    await stepHeader(3 + stepOffset, totalSteps, 'Instruction files');
+    await stepHeader(4, totalSteps, 'Instruction files');
 
     const mdFiles = await selectMdFiles(selected, targetDir);
 
@@ -482,25 +535,61 @@ export async function initCommand(options = {}) {
       process.exit(0);
     }
 
+    const allToInstall = expandWithBundled(selected);
+
+    // ── Download (only with --latest / --branch) ──────────────────
+    let activeTemplatePath = localTemplatePath;
+    if (useLatest) {
+      console.log();
+      await animatedSeparator(60);
+      console.log();
+      await stepHeader(5, totalSteps, 'Downloading latest framework');
+
+      const branchLabel = options.branch || 'main';
+      const branchBadge = chalk.hex('#2D3436').bgHex('#6C5CE7').bold(` ${branchLabel} `);
+      console.log(`  ${chalk.hex('#636E72')('Branch:')} ${branchBadge}`);
+      console.log();
+
+      try {
+        const result = await downloadWithSpinner({
+          branch: options.branch,
+          template: template,
+          foldersToExtract: allToInstall,
+          mdFiles: mdFiles,
+        });
+        tempDir = result.tempDir;
+        activeTemplatePath = await resolveTemplatePath(template, tempDir);
+
+        if (result.commitSha) {
+          const shaBadge = chalk.hex('#2D3436').bgHex('#00CEC9').bold(` ${result.commitSha.slice(0, 7)} `);
+          console.log(`  ${shaBadge} ${chalk.hex('#636E72')('latest commit')}`);
+        }
+        console.log();
+      } catch (err) {
+        console.log();
+        console.log(chalk.hex('#FDCB6E')(`  ⚠  ${err.message}`));
+        console.log(chalk.hex('#636E72')('  Falling back to bundled version...\n'));
+      }
+    }
+
     // ── Step: Install ─────────────────────────────────────────────
     console.log();
     await animatedSeparator(60);
     console.log();
-    await stepHeader(4 + stepOffset, totalSteps, 'Installing modules');
+    await stepHeader(useLatest ? 6 : 5, totalSteps, 'Installing modules');
 
-    const allToInstall = expandWithBundled(selected);
     let installed = 0;
     const errors = [];
 
     // Install module folders
     for (const folder of allToInstall) {
-      const displayName = formatFolderName(folder);
-      try {
-        await installWithAnimation(displayName, async () => {
-          await copyModule(folder, targetDir, frameworkPath);
-        });
-        installed++;
-      } catch (err) {
+        const displayName = formatFolderName(folder);
+        try {
+          await installWithAnimation(displayName, async () => {
+            await copyModule(folder, targetDir, activeTemplatePath);
+          });
+          installed++;
+        } catch (err) {
         errors.push({ folder, error: err.message });
       }
       await sleep(80);
@@ -510,7 +599,7 @@ export async function initCommand(options = {}) {
     for (const md of mdFiles) {
       try {
         await installWithAnimation(md, async () => {
-          await copyMdFile(md, targetDir, frameworkPath);
+          await copyMdFile(md, targetDir, activeTemplatePath);
         });
         installed++;
       } catch (err) {
@@ -521,6 +610,7 @@ export async function initCommand(options = {}) {
 
     // ── Final result ──────────────────────────────────────────────
     if (errors.length === 0) {
+      await saveTemplateSelection(targetDir, template);
       await celebrateSuccess(installed, targetDir);
       await setupPersistentMemory();
     } else {

package/src/commands/update.js

@@ -13,13 +13,18 @@
 import chalk from 'chalk';
 import gradient from 'gradient-string';
 import inquirer from 'inquirer';
-import { DESCRIPTIONS, ALWAYS_INSTALL, BUNDLED } from '../config/constants.js';
+import { DESCRIPTIONS, ALWAYS_INSTALL, BUNDLED, TEMPLATE_DESCRIPTIONS } from '../config/constants.js';
 import { AVAILABLE_MD_FILES, MD_DESCRIPTIONS } from '../config/ide-mapping.js';
-import { formatFolderName, sleep } from '../utils/helpers.js';
+import { formatFolderName, formatTemplateName, sleep } from '../utils/helpers.js';
 import {
   existsInTarget,
   copyModule,
   copyMdFile,
+  detectTemplateForModules,
+  getAvailableTemplates,
+  readTemplateSelection,
+  resolveTemplatePath,
+  saveTemplateSelection,
 } from '../services/installer.js';
 import { downloadWithSpinner, cleanupTempDir } from '../services/github-sync.js';
 import { showBanner } from '../ui/banner.js';
@@ -35,6 +40,16 @@ import {
 
 const acGradient = gradient(['#6C5CE7', '#00CEC9', '#0984E3']);
 
+function buildTemplateChoices(templates) {
+  return templates.map((template) => ({
+    name:
+      `${chalk.hex('#DFE6E9').bold(formatTemplateName(template))}` +
+      chalk.hex('#636E72')(` · ${TEMPLATE_DESCRIPTIONS[template] || 'Template for AI-assisted development workflows'}`),
+    value: template,
+    short: formatTemplateName(template),
+  }));
+}
+
 // ── Main command ─────────────────────────────────────────────────
 
 /**
@@ -118,6 +133,43 @@ export async function updateCommand(options = {}) {
 
   console.log();
 
+  // ── Step 2/3: Determine template ──────────────────────────────
+  let resolvedTemplate = await readTemplateSelection(targetDir);
+
+  if (!resolvedTemplate) {
+    const availableTemplates = await getAvailableTemplates();
+    const matches = [];
+
+    for (const template of availableTemplates) {
+      const templateSource = await resolveTemplatePath(template);
+      const isMatch = await Promise.all(installedModules.map((mod) => existsInTarget(templateSource, mod)));
+      if (isMatch.every(Boolean)) {
+        matches.push(template);
+      }
+    }
+
+    if (matches.length === 1) {
+      [resolvedTemplate] = matches;
+    } else if (matches.length > 1) {
+      console.log(chalk.hex('#FDCB6E')('  No saved template metadata found, and multiple templates match this project.'));
+      console.log();
+
+      const { selectedTemplate } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'selectedTemplate',
+          message: acGradient('Choose the template to use for this update:'),
+          choices: buildTemplateChoices(matches),
+          pageSize: 10,
+        },
+      ]);
+
+      resolvedTemplate = selectedTemplate;
+    } else {
+      resolvedTemplate = await detectTemplateForModules(installedModules);
+    }
+  }
+
   // ── Confirmation ──────────────────────────────────────────────
   const branchLabel = options.branch || 'main';
   const branchBadge = chalk.hex('#2D3436').bgHex('#6C5CE7').bold(` ${branchLabel} `);
@@ -145,11 +197,18 @@ export async function updateCommand(options = {}) {
 
   let tempDir = null;
   let commitSha = null;
+  let templatePath = null;
 
   try {
-    const result = await downloadWithSpinner({ branch: options.branch });
+    const result = await downloadWithSpinner({
+      branch: options.branch,
+      template: resolvedTemplate,
+      foldersToExtract: installedModules,
+      mdFiles: installedMdFiles,
+    });
     tempDir = result.tempDir;
     commitSha = result.commitSha;
+    templatePath = await resolveTemplatePath(resolvedTemplate, tempDir);
   } catch (err) {
     console.log();
     console.log(chalk.hex('#D63031')(`  ✗ ${err.message}`));
@@ -164,6 +223,14 @@ export async function updateCommand(options = {}) {
     console.log();
   }
 
+  if (resolvedTemplate) {
+    console.log(
+      chalk.hex('#636E72')('  Template source: ') +
+      chalk.hex('#DFE6E9')(resolvedTemplate)
+    );
+    console.log();
+  }
+
   // ── Step 3/3: Update modules ──────────────────────────────────
   await animatedSeparator(60);
   console.log();
@@ -175,13 +242,13 @@ export async function updateCommand(options = {}) {
   try {
     // Update module folders
     for (const mod of installedModules) {
-      const displayName = formatFolderName(mod);
-      try {
-        await installWithAnimation(displayName, async () => {
-          await copyModule(mod, targetDir, tempDir);
-        });
-        updated++;
-      } catch (err) {
+        const displayName = formatFolderName(mod);
+        try {
+          await installWithAnimation(displayName, async () => {
+            await copyModule(mod, targetDir, templatePath);
+          });
+          updated++;
+        } catch (err) {
         errors.push({ folder: mod, error: err.message });
       }
       await sleep(80);
@@ -191,7 +258,7 @@ export async function updateCommand(options = {}) {
     for (const md of installedMdFiles) {
       try {
         await installWithAnimation(md, async () => {
-          await copyMdFile(md, targetDir, tempDir);
+          await copyMdFile(md, targetDir, templatePath);
         });
         updated++;
       } catch (err) {
@@ -206,6 +273,9 @@ export async function updateCommand(options = {}) {
 
   // ── Results ───────────────────────────────────────────────────
   if (errors.length === 0) {
+    if (resolvedTemplate) {
+      await saveTemplateSelection(targetDir, resolvedTemplate);
+    }
     await celebrateSuccess(updated, targetDir);
   } else {
     await showFailureSummary(updated, errors);

package/src/config/constants.js

@@ -80,3 +80,54 @@ export const ASSISTANT_ICONS = {
   '.trae': '▸',
   '.windsurf': '◇',
 };
+
+export const TEMPLATE_DESCRIPTIONS = {
+  new_project: 'Best default for greenfield projects with the full skill catalog.',
+  mobile_development: 'Mobile-focused setup with general workflow skills and less web-specific specialization.',
+  web_development: 'Web-focused setup with UI, API, testing, performance, and React-oriented guidance.',
+};
+
+export const TEMPLATE_CAPABILITIES = {
+  new_project: [
+    'Full spec-driven workflow from planning to archive',
+    'Broad skill catalog for app, API, quality, and security work',
+    'Best starting point when project type is still flexible',
+  ],
+  mobile_development: [
+    'Spec-driven workflow plus general execution and documentation skills',
+    'Reduced specialization to keep the template lighter and more adaptable',
+    'Good fit for React Native, Flutter, Kotlin, Swift, or hybrid teams',
+  ],
+  web_development: [
+    'Web UI, API, testing, security, and performance oriented workflow',
+    'Includes interface and API design guidance for product development',
+    'Ideal for frontend, fullstack, dashboard, and SaaS-style projects',
+  ],
+};
+
+export const TEMPLATE_SKILL_PREVIEWS = {
+  new_project: [
+    'brainstorming',
+    'project-index',
+    'spec-clarification',
+    'test-generator',
+    'code-review',
+    'secure-coding-cybersecurity',
+  ],
+  mobile_development: [
+    'brainstorming',
+    'project-index',
+    'spec-analysis',
+    'context-synthesizer',
+    'systematic-debugging',
+    'openspec-apply-change',
+  ],
+  web_development: [
+    'api-design-principles',
+    'interface-design',
+    'vercel-react-best-practices',
+    'test-generator',
+    'performance-optimizer',
+    'secure-coding-cybersecurity',
+  ],
+};

package/src/config/ide-mapping.js

@@ -23,7 +23,7 @@ export const IDE_MD_MAP = {
   '.kimi': 'AGENTS.md',
   '.opencode': 'AGENTS.md',
   '.qoder': 'AGENTS.md',
-  '.qwen': 'QWEN.md',
+  '.qwen': 'AGENTS.md',
   '.roo': 'AGENTS.md',
   '.trae': 'AGENTS.md',
   '.windsurf': 'AGENTS.md',
@@ -43,6 +43,5 @@ export const MD_DESCRIPTIONS = {
   'AGENTS.md': 'Generic agent instructions (used by most assistants)',
   'CLAUDE.md': 'Anthropic Claude Code instructions',
   'GEMINI.md': 'Google Gemini instructions',
-  'QWEN.md': 'Qwen (Alibaba Cloud) instructions',
   'copilot-instructions.md': 'GitHub Copilot instructions',
 };

package/src/index.js

@@ -1,7 +1,20 @@
-export { getSelectableModules, expandWithBundled, copyModule, copyMdFile, FRAMEWORK_PATH } from './services/installer.js';
+export {
+  getAvailableTemplates,
+  getSelectableModules,
+  resolveTemplatePath,
+  expandWithBundled,
+  copyModule,
+  copyMdFile,
+  saveTemplateSelection,
+  readTemplateSelection,
+  detectTemplateForModules,
+  FRAMEWORK_PATH,
+  DEFAULT_TEMPLATE,
+  TEMPLATE_METADATA_FILE,
+} from './services/installer.js';
 export { downloadFramework, cleanupTempDir, downloadWithSpinner } from './services/github-sync.js';
 export { detectIDE } from './services/detector.js';
-export { ALWAYS_INSTALL, BUNDLED, DESCRIPTIONS, GITHUB_CONFIG } from './config/constants.js';
+export { ALWAYS_INSTALL, BUNDLED, DESCRIPTIONS, GITHUB_CONFIG, TEMPLATE_DESCRIPTIONS } from './config/constants.js';
 export { IDE_MD_MAP, AVAILABLE_MD_FILES } from './config/ide-mapping.js';
 export {
   initProject,

package/src/services/github-sync.js

@@ -60,7 +60,12 @@ function buildTarballUrl(branch) {
  * @param {string} frameworkDir - Name of the framework directory (default: "framework").
  * @returns {(entryPath: string) => boolean}
  */
-function createPathFilter(frameworkDir) {
+function createPathFilter(frameworkDir, options = {}) {
+  const { template, foldersToExtract, mdFiles } = options;
+
+  const hasFolderFilter = Array.isArray(foldersToExtract) && foldersToExtract.length > 0;
+  const hasMdFilter = Array.isArray(mdFiles) && mdFiles.length > 0;
+
   return (entryPath) => {
     const segments = entryPath.split('/').filter(Boolean);
 
@@ -71,7 +76,37 @@ function createPathFilter(frameworkDir) {
 
     // Only extract entries whose second segment is the framework dir
     // and that have actual content beyond it (length > 2).
-    return segments.length > 2 && segments[1] === frameworkDir;
+    if (segments.length > 2 && segments[1] === frameworkDir) {
+      // If we don't have filters, extract everything
+      if (!template) return true;
+
+      // Extract only the matching template directory
+      if (segments[2] !== template) return false;
+
+      // Inside the template directory, if we have specific folders/files to extract:
+      // apply each filter independently so we never fall back to full-template
+      // extraction when only one filter list is provided.
+      if (hasFolderFilter || hasMdFilter) {
+        const item = segments[3];
+        // If it's undefined, it's the template folder itself, keep it to allow its creation
+        if (!item) return true;
+
+        // If it's a file at the root of the template, check if it's in mdFiles
+        if (hasMdFilter && segments.length === 4 && item.endsWith('.md')) {
+          return mdFiles.includes(item);
+        }
+
+        // Check if it's one of the selected assistant folders.
+        if (hasFolderFilter && foldersToExtract.includes(item)) {
+          return true;
+        }
+
+        return false;
+      }
+
+      return true;
+    }
+    return false;
   };
 }
 
@@ -97,7 +132,7 @@ function createPathFilter(frameworkDir) {
  * @returns {Promise<{ tempDir: string, commitSha: string|null }>}
  * @throws {Error} On network failure, timeout, or GitHub API errors.
  */
-export async function downloadFramework({ branch, timeout } = {}) {
+export async function downloadFramework({ branch, timeout, template, foldersToExtract, mdFiles } = {}) {
   const url = buildTarballUrl(branch);
   const { frameworkDir } = GITHUB_CONFIG;
   const requestTimeout = timeout || GITHUB_CONFIG.timeout;
@@ -157,7 +192,7 @@ export async function downloadFramework({ branch, timeout } = {}) {
       tarExtract({
         cwd: tempDir,
         strip: 2,
-        filter: createPathFilter(frameworkDir),
+        filter: createPathFilter(frameworkDir, { template, foldersToExtract, mdFiles }),
       }),
     );