ac-framework 2.2.0 → 2.4.0

package/src/commands/agents.js

@@ -31,6 +31,7 @@ import {
   writeMeetingSummary,
 } from '../agents/state-store.js';
 import {
+  probeZellijCapabilities,
   roleLogPath,
   runTmux,
   runZellij,
@@ -153,6 +154,16 @@ async function attachToMux(multiplexer, sessionName, readonly = false, zellijPat
   await runTmux('tmux', args, { stdio: 'inherit' });
 }
 
+async function readZellijCapabilities(config) {
+  const zellijPath = resolveConfiguredZellijPath(config);
+  if (!zellijPath) return null;
+  try {
+    return await probeZellijCapabilities(zellijPath);
+  } catch {
+    return null;
+  }
+}
+
 function toMarkdownTranscript(state, transcript) {
   const displayedRound = Math.min(state.round, state.maxRounds);
   const lines = [
@@ -1270,6 +1281,7 @@ Examples:
         const muxResolution = resolveMultiplexerWithPaths(config, configuredMux);
         let selectedMux = muxResolution.selected;
         let zellijPath = muxResolution.zellijPath;
+        const tmuxPath = muxResolution.tmuxPath;
         if (!selectedMux) {
           if (configuredMux !== 'tmux' && shouldUseManagedZellij(config)) {
             const installResult = await installManagedZellijLatest();
@@ -1336,41 +1348,64 @@ Examples:
         const muxSessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
         const sessionDir = getSessionDir(state.sessionId);
 
-        if (selectedMux === 'zellij') {
-          await spawnZellijSession({
-            sessionName: muxSessionName,
-            sessionDir,
-            sessionId: state.sessionId,
-            binaryPath: zellijPath,
-          });
-        } else {
+        let activeMux = selectedMux;
+        let startupDiagnostics = null;
+        try {
+          if (selectedMux === 'zellij') {
+            startupDiagnostics = await spawnZellijSession({
+              sessionName: muxSessionName,
+              sessionDir,
+              sessionId: state.sessionId,
+              binaryPath: zellijPath,
+            });
+          } else {
+            await spawnTmuxSession({
+              sessionName: muxSessionName,
+              sessionDir,
+              sessionId: state.sessionId,
+            });
+          }
+        } catch (muxError) {
+          const canFallbackToTmux = configuredMux === 'auto' && selectedMux === 'zellij' && Boolean(tmuxPath);
+          if (!canFallbackToTmux) {
+            throw muxError;
+          }
+
+          if (!opts.json) {
+            console.log(chalk.yellow(`zellij startup failed, falling back to tmux: ${muxError.message}`));
+          }
           await spawnTmuxSession({
             sessionName: muxSessionName,
             sessionDir,
             sessionId: state.sessionId,
           });
+          activeMux = 'tmux';
         }
 
         const updated = await saveSessionState({
           ...state,
-          multiplexer: selectedMux,
+          multiplexer: activeMux,
           multiplexerSessionName: muxSessionName,
-          tmuxSessionName: selectedMux === 'tmux' ? muxSessionName : null,
+          tmuxSessionName: activeMux === 'tmux' ? muxSessionName : null,
         });
 
         output({
           sessionId: updated.sessionId,
-          multiplexer: selectedMux,
+          multiplexer: activeMux,
           multiplexerSessionName: muxSessionName,
           status: updated.status,
+          startupDiagnostics,
         }, opts.json);
         if (!opts.json) {
           printStartSummary(updated);
+          if (startupDiagnostics?.strategy) {
+            console.log(chalk.dim(`  zellij strategy: ${startupDiagnostics.strategy}`));
+          }
           printModelConfig(updated);
         }
 
         if (opts.attach) {
-          await attachToMux(selectedMux, muxSessionName, false, zellijPath);
+          await attachToMux(activeMux, muxSessionName, false, zellijPath);
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -1616,6 +1651,7 @@ Examples:
   agents
     .command('doctor')
     .description('Run diagnostics for SynapseGrid/OpenCode runtime')
+    .option('--verbose', 'Include backend capability details', false)
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
       try {
@@ -1638,8 +1674,13 @@ Examples:
           defaultModel,
           defaultRoleModels: cfg.agents.defaultRoleModels,
           preflight: null,
+          zellijCapabilities: null,
         };
 
+        if (opts.verbose && zellijPath) {
+          result.zellijCapabilities = await readZellijCapabilities(cfg);
+        }
+
         if (opencodeBin) {
           result.preflight = await preflightModel({
             opencodeBin,

package/src/config/constants.js

@@ -17,16 +17,16 @@ export const ALWAYS_INSTALL = [];
 // When a key module is selected, its bundled companions are auto-installed.
 export const BUNDLED = {
   '.cline': ['.clinerules'],
-  '.antigravity': ['.agent'],  // Antigravity uses .agent/skills/ directory
+  '.antigravity': ['.agents'],  // Antigravity uses .agents/skills/ directory
 };
 
 // Folders that should never appear in the selection list because they are
 // installed automatically as part of a bundled assistant.
-export const HIDDEN_FOLDERS = new Set([...Object.values(BUNDLED).flat(), '.agent']);
+export const HIDDEN_FOLDERS = new Set([...Object.values(BUNDLED).flat(), '.agents']);
 
 // Human-readable descriptions for each module, used in the selection UI.
 export const DESCRIPTIONS = {
-  '.agent': 'Generic Agent Framework',
+  '.agents': 'Generic Agent Framework',
   '.antigravity': 'Google Antigravity IDE (Agent-First)',
   '.amazonq': 'AWS Amazon Q',
   '.augment': 'Augment Code Assistant',
@@ -55,7 +55,7 @@ export const DESCRIPTIONS = {
 
 // Icons for each assistant, used in the selection UI.
 export const ASSISTANT_ICONS = {
-  '.agent': '⊡',
+  '.agents': '⊡',
   '.antigravity': '◉',
   '.amazonq': '◈',
   '.augment': '◇',
@@ -83,6 +83,7 @@ export const ASSISTANT_ICONS = {
 
 export const TEMPLATE_DESCRIPTIONS = {
   new_project: 'Best default for greenfield projects with the full skill catalog.',
+  make_your_own: 'General-purpose base where teams build their own skill repertoire without web-specific specializations.',
   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.',
 };
@@ -93,6 +94,11 @@ export const TEMPLATE_CAPABILITIES = {
     'Broad skill catalog for app, API, quality, and security work',
     'Best starting point when project type is still flexible',
   ],
+  make_your_own: [
+    'Includes all assistant/CLI and IDE packs from the base template',
+    'Keeps general OpenSpec, quality, security, and documentation skills',
+    'Encourages teams to curate and expand their own reusable skill stack',
+  ],
   mobile_development: [
     'Spec-driven workflow plus general execution and documentation skills',
     'Reduced specialization to keep the template lighter and more adaptable',
@@ -114,6 +120,14 @@ export const TEMPLATE_SKILL_PREVIEWS = {
     'code-review',
     'secure-coding-cybersecurity',
   ],
+  make_your_own: [
+    'brainstorming',
+    'project-index',
+    'spec-clarification',
+    'skill-writer',
+    'find-skills',
+    'sync-index',
+  ],
   mobile_development: [
     'brainstorming',
     'project-index',

package/src/config/ide-mapping.js

@@ -4,7 +4,7 @@
  * (the assistant uses a different mechanism, like .clinerules).
  */
 export const IDE_MD_MAP = {
-  '.agent': 'AGENTS.md',
+  '.agents': 'AGENTS.md',
   '.amazonq': 'AGENTS.md',
   '.augment': 'AGENTS.md',
   '.claude': 'CLAUDE.md',

package/src/mcp/collab-server.js

@@ -18,6 +18,7 @@ import { buildEffectiveRoleModels, sanitizeRoleModels } from '../agents/model-se
 import { runWorkerIteration } from '../agents/orchestrator.js';
 import { getSessionDir } from '../agents/state-store.js';
 import {
+  probeZellijCapabilities,
   spawnTmuxSession,
   spawnZellijSession,
   tmuxSessionExists,
@@ -84,6 +85,16 @@ function resolveConfiguredZellijPath(config) {
   return resolveCommandPath('zellij');
 }
 
+async function readZellijCapabilities(config) {
+  const zellijPath = resolveConfiguredZellijPath(config);
+  if (!zellijPath) return null;
+  try {
+    return await probeZellijCapabilities(zellijPath);
+  } catch {
+    return null;
+  }
+}
+
 async function muxExists(multiplexer, sessionName, zellijPath = null) {
   if (multiplexer === 'zellij') return zellijSessionExists(sessionName, zellijPath);
   return tmuxSessionExists(sessionName);
@@ -152,7 +163,13 @@ class MCPCollabServer {
             const sessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
             const sessionDir = getSessionDir(state.sessionId);
             if (multiplexer === 'zellij') {
-              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId, binaryPath: zellijPath });
+              await spawnZellijSession({
+                sessionName,
+                sessionDir,
+                sessionId: state.sessionId,
+                binaryPath: zellijPath,
+                capabilities: await readZellijCapabilities(config),
+              });
             } else {
               await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });
             }
@@ -477,7 +494,13 @@ class MCPCollabServer {
             const sessionDir = getSessionDir(state.sessionId);
             if (multiplexer === 'zellij') {
               if (!zellijPath) throw new Error('zellij is not installed. Run: acfm agents setup');
-              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId, binaryPath: zellijPath });
+              await spawnZellijSession({
+                sessionName,
+                sessionDir,
+                sessionId: state.sessionId,
+                binaryPath: zellijPath,
+                capabilities: await readZellijCapabilities(config),
+              });
             } else {
               if (!hasCommand('tmux')) throw new Error('tmux is not installed. Run: acfm agents setup');
               await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });

package/src/services/installer.js

@@ -7,7 +7,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 /** Absolute path to the bundled framework/ directory inside this package. */
 export const FRAMEWORK_PATH = resolve(__dirname, '../../framework');
-export const DEFAULT_TEMPLATE = 'new_project';
+export const DEFAULT_TEMPLATE = 'make_your_own';
 export const TEMPLATE_METADATA_FILE = '.acfm-template.json';
 
 function isTemplateDirectory(entry) {
@@ -110,7 +110,7 @@ export async function detectTemplateForModules(modules, frameworkPath = FRAMEWOR
  */
 export async function getSelectableModules(frameworkPath = FRAMEWORK_PATH) {
   const entries = await readdir(frameworkPath, { withFileTypes: true });
-  return entries
+  const physicalModules = entries
     .filter(
       (e) =>
         e.isDirectory() &&
@@ -118,8 +118,18 @@ export async function getSelectableModules(frameworkPath = FRAMEWORK_PATH) {
         !ALWAYS_INSTALL.includes(e.name) &&
         !HIDDEN_FOLDERS.has(e.name),
     )
-    .map((e) => e.name)
-    .sort((a, b) => a.localeCompare(b));
+    .map((e) => e.name);
+
+  // VIRTUAL MODULES:
+  // Add .antigravity to the list if it is not a physical directory,
+  // but only if the template actually contains the bundled target (.agents).
+  const virtualModules = [];
+  const allDirectories = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  if (!physicalModules.includes('.antigravity') && allDirectories.includes('.agents')) {
+    virtualModules.push('.antigravity');
+  }
+
+  return [...physicalModules, ...virtualModules].sort((a, b) => a.localeCompare(b));
 }
 
 /**
@@ -133,7 +143,13 @@ export function expandWithBundled(selected) {
       bundled.push(...BUNDLED[folder]);
     }
   }
-  return [...selected, ...bundled, ...ALWAYS_INSTALL];
+  const allSet = new Set([...selected, ...bundled, ...ALWAYS_INSTALL]);
+  
+  // Remove pure virtual aliases from installation list.
+  // .antigravity is just an alias for .agents now.
+  allSet.delete('.antigravity');
+  
+  return Array.from(allSet);
 }
 
 /**

package/framework/mobile_development/.agent/skills/sync-index/SKILL.md

@@ -1,35 +0,0 @@
----
-name: sync-index
-description: Keep project documentation (.agents/project-index.md and sub-skills) in sync with codebase changes.
----
-
-# Documentation Sync
-
-## Overview
-
-Documentation drift is a major problem. Use this skill to ensure that the project index and agent guidance files are always up-to-date with the codebase.
-
-## Workflow
-
-1.  **Detect Changes**:
-    *   Ideally run after major feature implementation or refactoring.
-    *   Compare current file structure with `project-index.md`.
-
-2.  **Run Indexer**:
-    *   Execute the `project-index` skill again.
-    *   Verify that new modules/directories are captured.
-    *   Ensure deleted files are removed from documentation.
-
-3.  **Update Guidance**:
-    *   Check `agent-*.md` files in domain directories.
-    *   Update any obsolete instructions.
-    *   Add new patterns discovered during implementation.
-
-4.  **Verify Links**:
-    *   Ensure all links in `README.md` and `AGENTS.md` point to valid locations.
-
-## Output
-
-*   Updated `project-index.md`.
-*   Updated domain-specific agent guides.
-*   Confirmation of documentation sync.

package/framework/mobile_development/.agent/workflows/ac-lite.md

@@ -1,130 +0,0 @@
-**Fundamental Principle**: *"Quality with focused context. Load only what is necessary, when it is necessary."*
-
----
-
-## Purpose
-
-`ac-lite` keeps OpenSpec rigor while reducing context load by:
-
-1. Loading only mandatory core workflow skills by default.
-2. Activating mobile/platform specialist skills only when objective gates trigger.
-3. Enforcing hard implementation and closure checkpoints.
-
----
-
-## Default Skill Set (Always Load)
-
-1. `acfm-spec-workflow`
-2. `acfm-memory`
-3. `openspec-new-change` OR `openspec-ff-change`
-4. `openspec-continue-change`
-5. `openspec-apply-change`
-6. `openspec-verify-change`
-7. `openspec-archive-change`
-8. `mobile-design`
-
----
-
-## Persistent Memory Protocol (Always Active)
-
-At session start:
-1. Recall project memory before planning or implementation.
-2. Search for task-specific patterns (architecture, bugfixes, conventions).
-3. Treat recalled memory as active unless repo state or user instructions override.
-
-Save reusable context after major decisions, fixes, and closures.
-
-Fallback CLI examples:
-```bash
-acfm memory recall
-acfm memory search "offline sync"
-acfm memory stats
-```
-
----
-
-## Conditional Skill Gates
-
-### Platform/Stack Gate
-Load based on selected implementation stack:
-- `flutter-expert` [IF Flutter]
-- `ios-developer` [IF native iOS]
-- `react-native-architecture` [IF React Native architecture/native modules]
-- `react-native-design` [IF React Native UI/navigation/animation]
-- `react-state-management` [IF global/complex state]
-
-### Platform UI Gate
-- `mobile-ios-design` [IF iOS UI changes]
-- `mobile-android-design` [IF Android UI changes]
-
-### Clarity/Scale Gate
-- `spec-clarification` [IF requirements ambiguous]
-- `spec-analysis` [IF cross-artifact consistency needs verification]
-- `microtask-decomposition` [IF tasks remain too complex]
-- `project-index` / `context-synthesizer` [IF repo/session scale requires]
-
-### Research Gate
-- `research-retrieval` [IF external docs are needed]
-
-### Debug Gate
-- `systematic-debugging` [IF blocked by bugs/regressions]
-
-### Delivery Gate
-- `documentation`, `sync-index`, `changelog-generator` [during closure]
-
----
-
-## Mandatory Quality Gates
-
-### Gate A: Ready to Implement
-Before `openspec-apply-change`, all must be true:
-- Change is initialized and valid (`acfm spec status --change <name> --json`)
-- `tasks.md` exists with actionable checkboxes
-- Platform and stack are explicit
-- Required conditional skills were executed
-- Session-start memory recall completed
-
-### Gate B: Ready to Close
-Before `openspec-archive-change`, all must be true:
-- `openspec-verify-change` completed
-- Critical issues resolved (or explicitly accepted with warning)
-- Task list reflects final state
-- Reusable context saved to memory
-- `documentation` / `sync-index` / changelog steps executed as required
-
----
-
-## Lite Workflow
-
-### New Mobile Change
-1. `acfm-spec-workflow` status/init checks.
-2. Session-start memory recall (`acfm-memory`).
-3. Start change (`openspec-new-change` or `openspec-ff-change`).
-4. Build artifacts (`openspec-continue-change`).
-5. Trigger and run only needed conditional skills.
-6. Pass Gate A.
-7. Implement (`openspec-apply-change`).
-8. Verify (`openspec-verify-change`).
-9. Pass Gate B.
-10. Archive/sync and generate closure docs.
-
-### Existing Mobile Change
-1. Confirm initialization and target change.
-2. Run memory recall.
-3. Refresh artifacts.
-4. Run only triggered conditional skills.
-5. Pass Gate A.
-6. Implement and debug as needed.
-7. Verify.
-8. Pass Gate B.
-9. Archive/sync.
-
----
-
-## Operational Rules
-
-1. Do not load non-triggered skills "just in case".
-2. Do not implement before platform/stack is explicit.
-3. If risk increases, load matching skill immediately.
-4. Keep outputs concise and auditable (which gates passed/failed and why).
-5. Save reusable memory at significant milestones.