ac-framework 1.0.0

package/framework/.windsurf/workflows/opsx-verify.md

@@ -0,0 +1,164 @@
+---
+name: "OPSX: Verify"
+description: Verify implementation matches change artifacts before archiving
+category: Workflow
+tags: [workflow, verify, experimental]
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

package/framework/openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "ac-framework",
+  "version": "1.0.0",
+  "description": "Agentic Coding Framework - Multi-assistant configuration system with OpenSpec workflows",
+  "main": "src/index.js",
+  "bin": {
+    "acfm": "bin/acfm.js"
+  },
+  "scripts": {
+    "test": "node src/cli.js init"
+  },
+  "keywords": [
+    "agentic",
+    "coding",
+    "framework",
+    "ai",
+    "assistant",
+    "openspec",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "gradient-string": "^3.0.0",
+    "inquirer": "^12.3.2",
+    "nanospinner": "^1.2.2",
+    "figlet": "^1.8.0"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "framework/",
+    "README.md"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { showBanner } from './ui/banner.js';
+
+const program = new Command();
+
+program
+  .name('acfm')
+  .description('AC Framework - Agentic Coding Framework CLI')
+  .version('1.0.0');
+
+program
+  .command('init')
+  .description('Initialize AC Framework modules in your project')
+  .action(async () => {
+    await showBanner();
+    await initCommand();
+  });
+
+program.parse();

package/src/commands/init.js

@@ -0,0 +1,275 @@
+import { readdir, cp, access } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import gradient from 'gradient-string';
+import inquirer from 'inquirer';
+import { createSpinner } from 'nanospinner';
+import { DESCRIPTIONS, formatFolderName, sleep } from '../utils/helpers.js';
+import { matrixRain, loadingAnimation, progressBar } from '../ui/animations.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const acGradient = gradient(['#6C5CE7', '#00CEC9', '#0984E3']);
+const successGradient = gradient(['#00CEC9', '#00B894', '#55EFC4']);
+
+async function getFrameworkFolders() {
+  const frameworkPath = resolve(__dirname, '../../framework');
+  const entries = await readdir(frameworkPath, { withFileTypes: true });
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((a, b) => {
+      // Hidden folders first, then normal
+      const aHidden = a.startsWith('.');
+      const bHidden = b.startsWith('.');
+      if (aHidden && !bHidden) return -1;
+      if (!aHidden && bHidden) return 1;
+      return a.localeCompare(b);
+    });
+}
+
+function buildChoices(folders) {
+  const choices = [];
+
+  const hidden = folders.filter((f) => f.startsWith('.'));
+  const visible = folders.filter((f) => !f.startsWith('.'));
+
+  if (hidden.length > 0) {
+    choices.push(new inquirer.Separator(chalk.hex('#636E72')('  ── AI Assistants ──────────────────────────')));
+    for (const folder of hidden) {
+      const desc = DESCRIPTIONS[folder] || '';
+      const displayName = formatFolderName(folder);
+      const label = `${chalk.hex('#DFE6E9').bold(displayName)}${desc ? chalk.hex('#636E72')(` — ${desc}`) : ''}`;
+      choices.push({
+        name: label,
+        value: folder,
+        short: displayName,
+      });
+    }
+  }
+
+  if (visible.length > 0) {
+    choices.push(new inquirer.Separator(chalk.hex('#636E72')('  ── Configuration ─────────────────────────')));
+    for (const folder of visible) {
+      const desc = DESCRIPTIONS[folder] || '';
+      const displayName = formatFolderName(folder);
+      const label = `${chalk.hex('#DFE6E9').bold(displayName)}${desc ? chalk.hex('#636E72')(` — ${desc}`) : ''}`;
+      choices.push({
+        name: label,
+        value: folder,
+        short: displayName,
+      });
+    }
+  }
+
+  return choices;
+}
+
+async function checkExisting(targetDir, folder) {
+  try {
+    await access(join(targetDir, folder));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function initCommand() {
+  const targetDir = process.cwd();
+
+  // Scanning animation
+  await loadingAnimation('Scanning available modules...', 800);
+  console.log();
+
+  // Matrix rain effect
+  console.log('\n'.repeat(6));
+  await matrixRain(1500);
+
+  let folders;
+  try {
+    folders = await getFrameworkFolders();
+  } catch {
+    console.log(chalk.red('  Error: Could not read framework directory.'));
+    console.log(chalk.hex('#636E72')('  Make sure ac-framework is installed correctly.'));
+    process.exit(1);
+  }
+
+  if (folders.length === 0) {
+    console.log(chalk.yellow('  No modules found in framework directory.'));
+    process.exit(0);
+  }
+
+  console.log(
+    chalk.hex('#B2BEC3')(`  Found ${chalk.hex('#00CEC9').bold(folders.length)} modules available\n`)
+  );
+
+  console.log(
+    chalk.hex('#636E72')('  Use ') +
+    chalk.hex('#00CEC9')('↑↓') +
+    chalk.hex('#636E72')(' to navigate, ') +
+    chalk.hex('#00CEC9')('Space') +
+    chalk.hex('#636E72')(' to select, ') +
+    chalk.hex('#00CEC9')('Enter') +
+    chalk.hex('#636E72')(' to confirm\n')
+  );
+
+  const choices = buildChoices(folders);
+
+  const { selected } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'selected',
+      message: acGradient('Select modules to install:'),
+      choices,
+      pageSize: 15,
+      loop: false,
+      validate(answer) {
+        if (answer.length === 0) {
+          return chalk.hex('#D63031')('You must select at least one module.');
+        }
+        return true;
+      },
+    },
+  ]);
+
+  console.log();
+
+  // Check for existing folders
+  const existing = [];
+  for (const folder of selected) {
+    if (await checkExisting(targetDir, folder)) {
+      existing.push(folder);
+    }
+  }
+
+  if (existing.length > 0) {
+    console.log(
+      chalk.hex('#FDCB6E')('  ⚠  The following modules already exist in your project:\n')
+    );
+    for (const folder of existing) {
+      console.log(chalk.hex('#FDCB6E')(`     • ${formatFolderName(folder)} (${folder})`));
+    }
+    console.log();
+
+    const { overwrite } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'overwrite',
+        message: chalk.hex('#FDCB6E')('Overwrite existing modules?'),
+        default: false,
+      },
+    ]);
+
+    if (!overwrite) {
+      const filtered = selected.filter((f) => !existing.includes(f));
+      if (filtered.length === 0) {
+        console.log(chalk.hex('#636E72')('\n  No new modules to install. Exiting.\n'));
+        process.exit(0);
+      }
+      selected.length = 0;
+      selected.push(...filtered);
+      console.log(
+        chalk.hex('#B2BEC3')(`\n  Proceeding with ${chalk.hex('#00CEC9').bold(selected.length)} new module(s)...\n`)
+      );
+    }
+  }
+
+  // Confirm selection
+  console.log(chalk.hex('#B2BEC3')('  Modules to install:\n'));
+  for (const folder of selected) {
+    const desc = DESCRIPTIONS[folder] || '';
+    console.log(
+      chalk.hex('#00CEC9')('  ◆ ') +
+      chalk.hex('#DFE6E9').bold(formatFolderName(folder)) +
+      (desc ? chalk.hex('#636E72')(` — ${desc}`) : '')
+    );
+  }
+  console.log();
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: chalk.hex('#B2BEC3')('Proceed with installation?'),
+      default: true,
+    },
+  ]);
+
+  if (!confirm) {
+    console.log(chalk.hex('#636E72')('\n  Installation cancelled.\n'));
+    process.exit(0);
+  }
+
+  console.log();
+
+  // Install modules with progress
+  const frameworkPath = resolve(__dirname, '../../framework');
+  let installed = 0;
+  const errors = [];
+
+  for (const folder of selected) {
+    const spinner = createSpinner(
+      chalk.hex('#B2BEC3')(`Installing ${chalk.hex('#DFE6E9').bold(formatFolderName(folder))}...`)
+    ).start();
+
+    try {
+      const src = join(frameworkPath, folder);
+      const dest = join(targetDir, folder);
+
+      await cp(src, dest, { recursive: true, force: true });
+
+      // Skip node_modules if copied
+      const nmPath = join(dest, 'node_modules');
+      try {
+        const { rm } = await import('node:fs/promises');
+        await rm(nmPath, { recursive: true, force: true });
+      } catch {
+        // node_modules didn't exist, that's fine
+      }
+
+      installed++;
+      spinner.success({
+        text:
+          chalk.hex('#00CEC9')(`  ${formatFolderName(folder)}`) +
+          chalk.hex('#636E72')(` → ${folder}/`),
+      });
+    } catch (err) {
+      errors.push({ folder, error: err.message });
+      spinner.error({
+        text: chalk.hex('#D63031')(`  Failed: ${formatFolderName(folder)} — ${err.message}`),
+      });
+    }
+
+    await sleep(150);
+  }
+
+  // Final summary
+  console.log();
+  console.log(
+    gradient(['#636E72', '#B2BEC3'])('  ─────────────────────────────────────────────────────────────────')
+  );
+  console.log();
+
+  if (errors.length === 0) {
+    await progressBar('Finalizing', 20, 600);
+    console.log();
+    console.log(successGradient('  ✓ Installation complete!'));
+    console.log();
+    console.log(
+      chalk.hex('#B2BEC3')(`  ${chalk.hex('#00CEC9').bold(installed)} module(s) installed successfully in ${chalk.hex('#DFE6E9')(targetDir)}`)
+    );
+  } else {
+    console.log(
+      chalk.hex('#FDCB6E')(`  ${installed} installed, ${errors.length} failed.`)
+    );
+  }
+
+  console.log();
+  console.log(
+    chalk.hex('#636E72')('  Your project is ready. Happy coding!')
+  );
+  console.log();
+}

package/src/ui/animations.js

@@ -0,0 +1,82 @@
+import chalk from 'chalk';
+import { createSpinner } from 'nanospinner';
+import { sleep } from '../utils/helpers.js';
+
+const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+export async function matrixRain(durationMs = 1500) {
+  const cols = Math.min(process.stdout.columns || 80, 80);
+  const drops = Array.from({ length: cols }, () => ({
+    y: Math.floor(Math.random() * 6),
+    speed: 1 + Math.floor(Math.random() * 3),
+    char: '',
+  }));
+  const chars = '01アイウエオカキクケコサシスセソタチツテトABCDEFacfm';
+  const colors = ['#00CEC9', '#0984E3', '#6C5CE7', '#00FF41'];
+  const rows = 6;
+  const frameTime = 60;
+  const totalFrames = Math.floor(durationMs / frameTime);
+
+  for (let frame = 0; frame < totalFrames; frame++) {
+    let output = '';
+    const grid = Array.from({ length: rows }, () => Array(cols).fill(' '));
+
+    for (let c = 0; c < cols; c++) {
+      const drop = drops[c];
+      if (drop.y < rows) {
+        const ch = chars[Math.floor(Math.random() * chars.length)];
+        grid[drop.y][c] = chalk.hex(colors[Math.floor(Math.random() * colors.length)])(ch);
+        if (drop.y > 0) {
+          grid[drop.y - 1][c] = chalk.hex('#2D3436')(
+            chars[Math.floor(Math.random() * chars.length)]
+          );
+        }
+      }
+      drop.y += drop.speed;
+      if (drop.y > rows + 3) {
+        drop.y = -Math.floor(Math.random() * 4);
+        drop.speed = 1 + Math.floor(Math.random() * 3);
+      }
+    }
+
+    for (const row of grid) {
+      output += '  ' + row.join('') + '\n';
+    }
+
+    process.stdout.write(`\x1B[${rows}A`);
+    process.stdout.write(output);
+    await sleep(frameTime);
+  }
+
+  // Clear the matrix area
+  process.stdout.write(`\x1B[${rows}A`);
+  for (let i = 0; i < rows; i++) {
+    process.stdout.write('\x1B[2K\n');
+  }
+  process.stdout.write(`\x1B[${rows}A`);
+}
+
+export async function loadingAnimation(text, durationMs = 1200) {
+  const spinner = createSpinner(chalk.hex('#B2BEC3')(text)).start();
+  await sleep(durationMs);
+  spinner.success({ text: chalk.hex('#00CEC9')(text) });
+}
+
+export async function progressBar(label, steps = 20, durationMs = 800) {
+  const filled = '█';
+  const empty = '░';
+  const barWidth = 30;
+
+  for (let i = 0; i <= steps; i++) {
+    const progress = Math.round((i / steps) * barWidth);
+    const bar =
+      chalk.hex('#6C5CE7')(filled.repeat(progress)) +
+      chalk.hex('#2D3436')(empty.repeat(barWidth - progress));
+    const pct = Math.round((i / steps) * 100);
+    process.stdout.write(
+      `\r  ${chalk.hex('#B2BEC3')(label)} ${bar} ${chalk.hex('#00CEC9')(`${pct}%`)}`
+    );
+    await sleep(durationMs / steps);
+  }
+  process.stdout.write('\n');
+}

package/src/ui/banner.js

@@ -0,0 +1,44 @@
+import figlet from 'figlet';
+import gradient from 'gradient-string';
+import chalk from 'chalk';
+import { sleep } from '../utils/helpers.js';
+
+const acGradient = gradient(['#6C5CE7', '#00CEC9', '#0984E3', '#6C5CE7']);
+const subtleGradient = gradient(['#636E72', '#B2BEC3']);
+
+export async function showBanner() {
+  console.clear();
+  console.log();
+
+  const asciiArt = figlet.textSync('AC  Framework', {
+    font: 'ANSI Shadow',
+    horizontalLayout: 'fitted',
+  });
+
+  // Typing animation for the ASCII art
+  const lines = asciiArt.split('\n');
+  for (const line of lines) {
+    console.log(acGradient(line));
+    await sleep(40);
+  }
+
+  console.log();
+  console.log(
+    subtleGradient('  ─────────────────────────────────────────────────────────────────')
+  );
+  console.log();
+
+  // Typewriter effect for tagline
+  const tagline = '  Agentic Coding Framework — Multi-assistant configuration system';
+  for (let i = 0; i <= tagline.length; i++) {
+    process.stdout.write(`\r${chalk.hex('#DFE6E9')(tagline.slice(0, i))}${chalk.hex('#00CEC9')('█')}`);
+    await sleep(12);
+  }
+  process.stdout.write(`\r${chalk.hex('#DFE6E9')(tagline)}  \n`);
+
+  console.log();
+  console.log(
+    subtleGradient('  ─────────────────────────────────────────────────────────────────')
+  );
+  console.log();
+}

package/src/utils/helpers.js

@@ -0,0 +1,36 @@
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function formatFolderName(name) {
+  // Remove leading dot for display
+  const clean = name.startsWith('.') ? name.slice(1) : name;
+  return clean.charAt(0).toUpperCase() + clean.slice(1);
+}
+
+export const DESCRIPTIONS = {
+  '.agent': 'Generic Agent Framework',
+  '.amazonq': 'AWS Amazon Q',
+  '.augment': 'Augment Code Assistant',
+  '.claude': 'Anthropic Claude Code',
+  '.cline': 'Cline VS Code Extension',
+  '.clinerules': 'Cline Shared Rules',
+  '.codebuddy': 'CodeBuddy Assistant',
+  '.codex': 'OpenAI Codex CLI',
+  '.continue': 'Continue.dev IDE Extension',
+  '.cospec': 'OpenSpec Native Framework',
+  '.crush': 'Crush Assistant',
+  '.cursor': 'Cursor IDE',
+  '.factory': 'Factory Assistant',
+  '.gemini': 'Google Gemini',
+  '.github': 'GitHub Copilot',
+  '.iflow': 'iFlow Assistant',
+  '.kilocode': 'Kilo Code',
+  '.opencode': 'OpenCode Framework',
+  '.qoder': 'Qoder Assistant',
+  '.qwen': 'Qwen (Alibaba Cloud)',
+  '.roo': 'Roo Code Extension',
+  '.trae': 'Trae IDE',
+  '.windsurf': 'Windsurf IDE',
+  'openspec': 'OpenSpec Configuration',
+};