ardfw 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# Agentics Framework
+
+An AI agentics framework for building multi-agent systems focused on software engineering, datascience research, and personal knowledge management. Built for Claude Code and Claude Agent SDK, with support for other agentics platforms like OpenCode and Cursor.
+
+## The Problem
+
+Building robust multi-agent systems is challenging:
+- **Inconsistent agent definitions** - Each agent defined differently across projects
+- **Skill duplication** - Writing the same capabilities for different agents
+- **Workflow complexity** - Orchestrating commands and agents is ad-hoc
+- **Limited extensibility** - Hard to add custom skills and MCP servers
+
+## The Solution
+
+This framework provides a standardized system for:
+- **Standardized Agent Definitions** - Consistent structure for defining specialized agents
+- **Reusable Skill Library** - Build skills once, use across multiple agents
+- **Command Workflow Automation** - Chain commands and agents for complex workflows
+- **Custom Skills & MCP Servers** - Extend agents with custom capabilities and MCP integrations
+
+## Architecture
+
+The framework is built on the **ARD** design pattern:
+
+- **Abstract** - Take existing methods and abstract them to understand underlying frameworks and context from user input
+- **Refactor** - Modularize and reorganize ideas from abstraction
+- **Derivative** - Derive new specialized variations from existing ideas
+
+### Core Components
+
+The framework has three essential building blocks that work together:
+
+#### 1. **Agents** (`/agents`)
+Specialized AI agents with defined roles and capabilities. Each agent is a prompt template with specific expertise (e.g., architect, developer, analyst, tech-writer, etc.). These are the primary abstractions users work with.
+
+**Examples:**
+- `architect.md` - Architecture and design decisions
+- `dev.md` - Software development and coding
+- `analyst.md` - Data analysis and research
+- `tech-writer.md` - Documentation and technical writing
+- `pm.md` - Project management
+- `ux-designer.md` - UI/UX design
+- `sm.md` - Scrum/agile management
+- `agent-dev.md` - Building custom agents
+
+#### 2. **Commands** (`/commands`)
+Reusable Claude Code commands that orchestrate agents and define workflows. Commands are executed via Claude Code and can chain multiple agents together.
+
+**Core commands:**
+- `prime.md` - Understand a codebase quickly
+- `quick-plan.md` - Create rapid implementation plans
+- `build.md` - Execute implementations
+- `meta-prompt.md` - Generate new command prompts
+- `load_ai_docs.md` - Load documentation context
+- `parallel_subagents.md` - Orchestrate multiple agents in parallel
+
+**Expert commands** (`/commands/experts`)
+- `plan.md` - Create detailed implementation plans
+- `build.md` - Execute plans with expert guidance
+- `plan-build-improve.md` - Complete workflow with continuous improvement
+- `self-improve.md` - Update expertise based on learnings
+
+#### 3. **Skills** (`/skills`)
+Reusable capabilities that agents can use. Skills are MCP servers, tools, and utility functions that extend agent capabilities.
+
+**Examples:**
+- Custom MCP servers for domain-specific tasks
+- Tool definitions for agent use
+- Integration skills for connecting to external systems
+
+### Project Structure
+
+```
+agentics/
+├── agents/                 # Agent definitions
+│   ├── architect.md
+│   ├── dev.md
+│   ├── analyst.md
+│   └── ... (other agents)
+├── commands/              # Command workflows
+│   ├── prime.md
+│   ├── quick-plan.md
+│   ├── build.md
+│   └── experts/          # Expert command variants
+└── skills/               # Reusable skills & MCP servers
+    └── meta-skills/
+```
+
+Project-specific workflows and templates are built **outside** these core folders in your project directory.
+
+## Getting Started
+
+### Installation & Setup
+
+1. **Clone this repository** to your `_ard` folder or relevant configuration directory:
+   ```bash
+   git clone <repo> ~/_ard/agentics
+   ```
+
+2. **Symlink to your projects** - Link the framework into your project directories:
+   ```bash
+   ln -s ~/_ard/agentics/agents ./project/_ard/agents
+   ln -s ~/_ard/agentics/commands ./project/_ard/commands
+   ln -s ~/_ard/agentics/skills ./project/_ard/skills
+   ```
+
+3. **Use in Claude Code** - Reference agents and commands in your Claude Code workflows
+
+### Your First Agent
+
+1. Start with the `prime` command to understand your codebase:
+   ```
+   /prime
+   ```
+
+2. Create a plan using `quick-plan`:
+   ```
+   /quick-plan
+   ```
+
+3. Execute with the appropriate agent (architect for design, dev for implementation, etc.)
+
+### Creating Custom Agents
+
+Use the `agent-dev.md` agent or `meta-prompt` command to create new specialized agents:
+
+```
+/meta-prompt "Create a [Role] agent that handles [Responsibility]"
+```
+
+### Creating Custom Skills
+
+Define custom skills in the `/skills` directory following the established patterns. Skills can be:
+- MCP servers
+- Tool definitions
+- Integration wrappers
+
+## Platform Compatibility
+
+- **Primary**: Claude Code & Claude Agent SDK
+- **Compatible**: OpenCode, Cursor, and other agentics platforms (with adaptations)
+
+## Current Status
+
+**Internal/Experimental** - This framework is actively being developed. It's suitable for internal use and early adopter feedback, but not yet production-ready for external distribution.
+
+## Next Steps
+
+- [ ] Define each agent's specific capabilities and use cases
+- [ ] Build a comprehensive skill library with examples
+- [ ] Create workflow templates for common scenarios
+- [ ] Document best practices for extending the framework
+- [ ] Add examples and sample projects
+
+## Contributing
+
+For internal development:
+1. Create new agent definitions in `/agents`
+2. Add commands in `/commands`
+3. Extend skills in `/skills`
+4. Follow the ARD pattern for consistency

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "ardfw",
+  "version": "0.1.0",
+  "description": "Agentics Framework CLI - Multi-agent system for Claude Code and OpenCode",
+  "bin": {
+    "ardfw": "tools/ard-npx-wrapper.js",
+    "ard": "tools/ard-npx-wrapper.js"
+  },
+  "files": [
+    "tools/",
+    "src/project_config/"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\"",
+    "ard:install": "node tools/ard-npx-wrapper.js install"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.0",
+    "yaml": "^2.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uechanx/agentics.git"
+  },
+  "keywords": [
+    "agentics",
+    "claude-code",
+    "opencode",
+    "ai-agents",
+    "cli"
+  ],
+  "author": "uechanx",
+  "license": "MIT"
+}

package/src/project_config/AGENTICS.md

@@ -0,0 +1,19 @@
+# Project: {{PROJECT_NAME}}
+
+## Overview
+<!-- Describe your project here -->
+
+## Tech Stack
+<!-- List key technologies, frameworks, and tools -->
+
+## Project Structure
+<!-- Describe directory layout and organization -->
+
+## Conventions
+<!-- Document coding conventions, naming patterns, etc. -->
+
+## Development Commands
+<!-- Common dev commands for building, testing, running -->
+
+## Notes for AI Agents
+<!-- Special instructions, constraints, or context for AI assistance -->

package/src/project_config/settings.json

@@ -0,0 +1,3 @@
+{
+  "spinnerTipsEnabled": true
+}

package/tools/ard-npx-wrapper.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * ard CLI wrapper
+ * Handles npx execution context and delegates to main CLI
+ */
+
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Detect if running through npx (npm cache directory)
+const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
+
+if (isNpxExecution) {
+  // Running via npx - spawn child process to preserve CWD
+  const ardCliPath = path.join(__dirname, 'cli', 'ard-cli.js');
+  const args = process.argv.slice(2);
+
+  try {
+    execSync(`node "${ardCliPath}" ${args.join(' ')}`, {
+      stdio: 'inherit',
+      cwd: process.cwd(), // Preserve user's working directory
+    });
+  } catch (error) {
+    process.exit(error.status || 1);
+  }
+} else {
+  // Running locally - dynamic import
+  await import('./cli/ard-cli.js');
+}

package/tools/cli/ard-cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * ard CLI - Agentics Framework installer
+ */
+
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Load package.json for version
+const packageJsonPath = path.resolve(__dirname, '../../package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+const program = new Command();
+
+program
+  .name('ard')
+  .description('Agentics Framework CLI - Multi-agent system for Claude Code and OpenCode')
+  .version(packageJson.version);
+
+// Dynamically load commands from commands/ directory
+const commandsDir = path.join(__dirname, 'commands');
+
+if (fs.existsSync(commandsDir)) {
+  const commandFiles = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.js'));
+
+  for (const file of commandFiles) {
+    const commandModule = await import(path.join(commandsDir, file));
+    const command = commandModule.default;
+
+    const cmd = program.command(command.command).description(command.description);
+
+    // Add options if defined
+    if (command.options) {
+      for (const opt of command.options) {
+        cmd.option(...opt);
+      }
+    }
+
+    cmd.action(command.action);
+  }
+}
+
+// Show help if no command provided
+if (process.argv.length <= 2) {
+  program.help();
+}
+
+program.parse(process.argv);

package/tools/cli/commands/install.js

@@ -0,0 +1,81 @@
+/**
+ * install command - Sets up Agentics in a project
+ */
+
+import Installer from '../lib/installer.js';
+import UI from '../lib/ui.js';
+import chalk from 'chalk';
+
+export default {
+  command: 'install',
+  description: 'Install Agentics Framework in current project',
+  options: [
+    ['--force', 'Overwrite existing installation'],
+    ['--claude', 'Enable Claude Code integration'],
+    ['--opencode', 'Enable OpenCode integration'],
+    ['-y, --yes', 'Skip prompts, use defaults'],
+  ],
+
+  async action(options) {
+    const ui = new UI();
+    const installer = new Installer();
+
+    console.log(chalk.blue('\n🤖 Agentics Framework Installer\n'));
+
+    try {
+      // Check for existing installation
+      const existing = installer.checkExisting();
+
+      if (existing && !options.force) {
+        if (options.yes) {
+          // In non-interactive mode with existing install, just update
+          await installer.update();
+          console.log(chalk.green('\n✅ Agentics updated successfully!'));
+          return;
+        }
+
+        const { action } = await ui.promptExistingInstall(existing);
+
+        if (action === 'cancel') {
+          console.log(chalk.yellow('Installation cancelled.'));
+          return;
+        }
+
+        if (action === 'update') {
+          await installer.update();
+          console.log(chalk.green('\n✅ Agentics updated successfully!'));
+          return;
+        }
+      }
+
+      // Gather installation options
+      let config;
+      if (options.yes) {
+        config = {
+          enableClaude: options.claude !== false,
+          enableOpenCode: options.opencode || false,
+          projectName: 'my-project',
+        };
+      } else {
+        config = await ui.promptInstall(existing);
+      }
+
+      if (config.cancelled) {
+        console.log(chalk.yellow('Installation cancelled.'));
+        return;
+      }
+
+      // Run installation
+      await installer.install(config);
+
+      // Show success message
+      ui.showSuccess(config);
+    } catch (error) {
+      console.error(chalk.red('\n❌ Installation failed:'), error.message);
+      if (process.env.DEBUG) {
+        console.error(error.stack);
+      }
+      process.exit(1);
+    }
+  },
+};

package/tools/cli/lib/config.js

@@ -0,0 +1,48 @@
+/**
+ * Configuration constants for ARD CLI
+ */
+
+export const PATHS = {
+  ARD_DIR: '_ard',
+  PROJECT_CONFIG: '_ard/project_config',
+  CONFIG_YAML: '_ard/config.yaml',
+  MANIFEST: '_ard/.manifest.json',
+  ARTIFACTS: '_ard/artifacts',
+};
+
+export const DEFAULT_CONFIG = {
+  project_name: 'my-project',
+  user_name: 'User',
+  output_folder: '_ard/artifacts',
+  planning_artifacts: '_ard/artifacts/planning',
+  implementation_artifacts: '_ard/artifacts/implementation',
+  product_knowledge: 'docs',
+  communication_language: 'en',
+  document_output_language: 'en',
+  user_skill_level: 'intermediate',
+};
+
+export const IDE_CONFIGS = {
+  claude: {
+    id: 'claude',
+    name: 'Claude Code',
+    linkName: '.claude',
+    contextFile: 'CLAUDE.md',
+    sourceContextFile: 'AGENTICS.md',
+  },
+  opencode: {
+    id: 'opencode',
+    name: 'OpenCode',
+    linkName: '.opencode',
+    contextFile: 'OPENCODE.md',
+    sourceContextFile: 'AGENTICS.md',
+  },
+};
+
+export const SYMLINK_MAPPINGS = [
+  { source: 'AGENTICS.md', targets: { claude: 'CLAUDE.md', opencode: 'OPENCODE.md' } },
+  { source: 'settings.json', targets: { claude: 'settings.json', opencode: 'settings.json' } },
+  { source: 'agents', targets: { claude: 'agents', opencode: 'agents' }, isDir: true },
+  { source: 'commands', targets: { claude: 'commands', opencode: 'commands' }, isDir: true },
+  { source: 'skills', targets: { claude: 'skills', opencode: 'skills' }, isDir: true },
+];

package/tools/cli/lib/file-ops.js

@@ -0,0 +1,76 @@
+/**
+ * File operations utilities
+ */
+
+import fs from 'fs-extra';
+import path from 'node:path';
+
+export default class FileOps {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+  }
+
+  resolve(...paths) {
+    return path.join(this.projectRoot, ...paths);
+  }
+
+  async exists(filePath) {
+    return fs.pathExists(this.resolve(filePath));
+  }
+
+  async isSymlink(filePath) {
+    try {
+      const stat = await fs.lstat(this.resolve(filePath));
+      return stat.isSymbolicLink();
+    } catch {
+      return false;
+    }
+  }
+
+  async readSymlink(linkPath) {
+    return fs.readlink(this.resolve(linkPath));
+  }
+
+  async ensureDir(dirPath) {
+    return fs.ensureDir(this.resolve(dirPath));
+  }
+
+  async copy(src, dest, options = {}) {
+    return fs.copy(this.resolve(src), this.resolve(dest), options);
+  }
+
+  async writeFile(filePath, content) {
+    await fs.ensureDir(path.dirname(this.resolve(filePath)));
+    return fs.writeFile(this.resolve(filePath), content);
+  }
+
+  async readFile(filePath) {
+    return fs.readFile(this.resolve(filePath), 'utf8');
+  }
+
+  async remove(filePath) {
+    return fs.remove(this.resolve(filePath));
+  }
+
+  async symlink(target, linkPath, type = 'file') {
+    const fullLinkPath = this.resolve(linkPath);
+    await fs.ensureDir(path.dirname(fullLinkPath));
+
+    // Remove existing symlink if present
+    if (await this.isSymlink(linkPath)) {
+      await this.remove(linkPath);
+    }
+
+    // Create relative symlink
+    return fs.symlink(target, fullLinkPath, type);
+  }
+
+  async writeJson(filePath, data, options = { spaces: 2 }) {
+    await fs.ensureDir(path.dirname(this.resolve(filePath)));
+    return fs.writeJson(this.resolve(filePath), data, options);
+  }
+
+  async readJson(filePath) {
+    return fs.readJson(this.resolve(filePath));
+  }
+}

package/tools/cli/lib/installer.js

@@ -0,0 +1,261 @@
+/**
+ * Installer - Core installation logic
+ */
+
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as yaml from 'yaml';
+import FileOps from './file-ops.js';
+import { PATHS, DEFAULT_CONFIG, IDE_CONFIGS, SYMLINK_MAPPINGS } from './config.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default class Installer {
+  constructor() {
+    this.projectRoot = process.cwd();
+    this.packageRoot = path.resolve(__dirname, '../../..');
+    this.fileOps = new FileOps(this.projectRoot);
+  }
+
+  /**
+   * Check for existing Agentics installation
+   */
+  checkExisting() {
+    const ardPath = path.join(this.projectRoot, PATHS.ARD_DIR);
+    const configPath = path.join(this.projectRoot, PATHS.CONFIG_YAML);
+
+    if (!fs.existsSync(ardPath)) {
+      return null;
+    }
+
+    try {
+      if (fs.existsSync(configPath)) {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const config = yaml.parse(content);
+        return {
+          path: ardPath,
+          version: config.ard_version || 'unknown',
+          config,
+        };
+      }
+    } catch {
+      // Corrupted config
+    }
+
+    return { path: ardPath, version: 'unknown', config: null };
+  }
+
+  /**
+   * Get package version
+   */
+  getVersion() {
+    const packageJsonPath = path.join(this.packageRoot, 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return packageJson.version;
+  }
+
+  /**
+   * Main installation
+   */
+  async install(options) {
+    const { enableClaude = true, enableOpenCode = false, projectName = 'my-project' } = options;
+
+    // 1. Create _ard directory structure
+    await this._createArdDirectory();
+
+    // 2. Copy project_config template
+    await this._copyProjectConfig();
+
+    // 3. Create config.yaml
+    await this._createConfigYaml(projectName, enableClaude, enableOpenCode);
+
+    // 4. Create artifacts directory
+    await this._createArtifactsDirectory();
+
+    // 5. Create IDE symlinks
+    if (enableClaude) {
+      await this._createIdeSymlinks('claude');
+    }
+    if (enableOpenCode) {
+      await this._createIdeSymlinks('opencode');
+    }
+
+    // 6. Create manifest for tracking
+    await this._createManifest(options);
+  }
+
+  /**
+   * Update existing installation
+   */
+  async update() {
+    // Read existing config
+    const existing = this.checkExisting();
+    if (!existing) {
+      throw new Error('No existing installation found');
+    }
+
+    // Backup existing project_config
+    const projectConfigPath = path.join(this.projectRoot, PATHS.PROJECT_CONFIG);
+    const backupPath = path.join(this.projectRoot, '_ard/project_config.backup');
+
+    if (fs.existsSync(projectConfigPath)) {
+      await fs.copy(projectConfigPath, backupPath);
+    }
+
+    // Copy new template, preserving user files
+    await this._copyProjectConfig({ merge: true });
+
+    // Update config.yaml version
+    await this._updateConfigVersion();
+  }
+
+  // === Private Methods ===
+
+  async _createArdDirectory() {
+    await this.fileOps.ensureDir(PATHS.ARD_DIR);
+  }
+
+  async _copyProjectConfig(options = {}) {
+    const srcPath = path.join(this.packageRoot, 'src/project_config');
+    const destPath = path.join(this.projectRoot, PATHS.PROJECT_CONFIG);
+
+    // Ensure source exists
+    if (!fs.existsSync(srcPath)) {
+      // Create minimal template if source doesn't exist yet
+      await this._createMinimalTemplate(destPath);
+      return;
+    }
+
+    await fs.copy(srcPath, destPath, {
+      overwrite: !options.merge, // Don't overwrite in merge mode
+      errorOnExist: false,
+    });
+  }
+
+  async _createMinimalTemplate(destPath) {
+    await fs.ensureDir(destPath);
+    await fs.ensureDir(path.join(destPath, 'agents'));
+    await fs.ensureDir(path.join(destPath, 'commands'));
+    await fs.ensureDir(path.join(destPath, 'skills'));
+
+    // Create AGENTICS.md
+    const agenticsContent = `# Project: ${path.basename(this.projectRoot)}
+
+## Overview
+<!-- Describe your project here -->
+
+## Tech Stack
+<!-- List key technologies -->
+
+## Project Structure
+<!-- Describe directory layout -->
+
+## Conventions
+<!-- Document coding conventions -->
+
+## Development Commands
+<!-- Common dev commands -->
+
+## Notes for AI Agents
+<!-- Special instructions -->
+`;
+    await fs.writeFile(path.join(destPath, 'AGENTICS.md'), agenticsContent);
+
+    // Create settings.json
+    await fs.writeJson(path.join(destPath, 'settings.json'), { spinnerTipsEnabled: true }, { spaces: 2 });
+
+    // Create .gitkeep files
+    await fs.writeFile(path.join(destPath, 'agents/.gitkeep'), '');
+    await fs.writeFile(path.join(destPath, 'commands/.gitkeep'), '');
+    await fs.writeFile(path.join(destPath, 'skills/.gitkeep'), '');
+  }
+
+  async _createConfigYaml(projectName, enableClaude, enableOpenCode) {
+    const configPath = path.join(this.projectRoot, PATHS.CONFIG_YAML);
+
+    // Don't overwrite existing config
+    if (fs.existsSync(configPath)) {
+      return;
+    }
+
+    const config = {
+      ...DEFAULT_CONFIG,
+      project_name: projectName,
+      ard_version: this.getVersion(),
+      ides: {
+        claude: enableClaude,
+        opencode: enableOpenCode,
+      },
+    };
+
+    const yamlContent = yaml.stringify(config);
+    await fs.writeFile(configPath, `# Agentics Framework Configuration\n${yamlContent}`);
+  }
+
+  async _createArtifactsDirectory() {
+    const dirs = [PATHS.ARTIFACTS, `${PATHS.ARTIFACTS}/planning`, `${PATHS.ARTIFACTS}/implementation`];
+
+    for (const dir of dirs) {
+      await this.fileOps.ensureDir(dir);
+    }
+  }
+
+  async _createIdeSymlinks(ideId) {
+    const ideConfig = IDE_CONFIGS[ideId];
+    const idePath = path.join(this.projectRoot, ideConfig.linkName);
+
+    // Check if IDE directory exists and is not a symlink
+    if (fs.existsSync(idePath)) {
+      const stat = fs.lstatSync(idePath);
+      if (!stat.isSymbolicLink()) {
+        throw new Error(
+          `${ideConfig.linkName} exists and is not a symlink. ` +
+            `Please remove or rename it before installing.`
+        );
+      }
+      // Remove existing symlink
+      await fs.remove(idePath);
+    }
+
+    // Create IDE directory
+    await fs.ensureDir(idePath);
+
+    // Create individual symlinks for each file/directory
+    for (const mapping of SYMLINK_MAPPINGS) {
+      const sourcePath = path.join('..', PATHS.PROJECT_CONFIG, mapping.source);
+      const targetName = mapping.targets[ideId];
+      const targetPath = path.join(idePath, targetName);
+
+      // Create symlink
+      const symlinkType = mapping.isDir ? 'dir' : 'file';
+      await fs.symlink(sourcePath, targetPath, symlinkType);
+    }
+  }
+
+  async _createManifest(options) {
+    const manifestPath = path.join(this.projectRoot, PATHS.MANIFEST);
+
+    const manifest = {
+      installed_at: new Date().toISOString(),
+      version: this.getVersion(),
+      options: {
+        enableClaude: options.enableClaude,
+        enableOpenCode: options.enableOpenCode,
+      },
+    };
+
+    await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+  }
+
+  async _updateConfigVersion() {
+    const configPath = path.join(this.projectRoot, PATHS.CONFIG_YAML);
+    const content = await fs.readFile(configPath, 'utf8');
+    const config = yaml.parse(content);
+
+    config.ard_version = this.getVersion();
+
+    await fs.writeFile(configPath, yaml.stringify(config));
+  }
+}

package/tools/cli/lib/ui.js

@@ -0,0 +1,134 @@
+/**
+ * UI - Interactive prompts for installation
+ */
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import path from 'node:path';
+import { IDE_CONFIGS } from './config.js';
+
+export default class UI {
+  async promptExistingInstall(existing) {
+    const { action } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: `Agentics already installed (v${existing.version}). What would you like to do?`,
+        choices: [
+          { name: 'Update to latest version', value: 'update' },
+          { name: 'Reinstall (overwrites config)', value: 'reinstall' },
+          { name: 'Cancel', value: 'cancel' },
+        ],
+      },
+    ]);
+
+    return { action };
+  }
+
+  async promptInstall(existing) {
+    const answers = {};
+
+    // IDE Selection
+    const { ides } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'ides',
+        message: 'Select IDE integrations:',
+        choices: [
+          {
+            name: `${IDE_CONFIGS.claude.name} (${IDE_CONFIGS.claude.linkName}/)`,
+            value: 'claude',
+            checked: true,
+          },
+          {
+            name: `${IDE_CONFIGS.opencode.name} (${IDE_CONFIGS.opencode.linkName}/)`,
+            value: 'opencode',
+            checked: false,
+          },
+        ],
+        validate: (input) => {
+          if (input.length === 0) {
+            return 'Please select at least one IDE integration.';
+          }
+          return true;
+        },
+      },
+    ]);
+
+    answers.enableClaude = ides.includes('claude');
+    answers.enableOpenCode = ides.includes('opencode');
+
+    // Project name (optional)
+    const { projectName } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'projectName',
+        message: 'Project name (for config):',
+        default: this._inferProjectName(),
+      },
+    ]);
+
+    answers.projectName = projectName;
+
+    // Confirmation
+    console.log(chalk.dim('\nInstallation summary:'));
+    console.log(chalk.dim('  - Create _ard/ directory'));
+    console.log(chalk.dim('  - Copy project_config template'));
+    if (answers.enableClaude) {
+      console.log(chalk.dim(`  - Symlink ${IDE_CONFIGS.claude.linkName}/ -> _ard/project_config/`));
+    }
+    if (answers.enableOpenCode) {
+      console.log(chalk.dim(`  - Symlink ${IDE_CONFIGS.opencode.linkName}/ -> _ard/project_config/`));
+    }
+
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: 'Proceed with installation?',
+        default: true,
+      },
+    ]);
+
+    if (!confirm) {
+      answers.cancelled = true;
+    }
+
+    return answers;
+  }
+
+  showSuccess(config) {
+    console.log(chalk.green('\n✅ Agentics Framework installed successfully!\n'));
+
+    console.log(chalk.bold('Created:'));
+    console.log(`  ${chalk.cyan('_ard/')}`);
+    console.log('    ├── config.yaml');
+    console.log('    ├── project_config/');
+    console.log('    │   ├── AGENTICS.md');
+    console.log('    │   ├── settings.json');
+    console.log('    │   ├── agents/');
+    console.log('    │   ├── commands/');
+    console.log('    │   └── skills/');
+    console.log('    └── artifacts/');
+
+    if (config.enableClaude) {
+      console.log(`  ${chalk.cyan('.claude/')} (symlinked to _ard/project_config/)`);
+      console.log('    └── CLAUDE.md -> AGENTICS.md');
+    }
+    if (config.enableOpenCode) {
+      console.log(`  ${chalk.cyan('.opencode/')} (symlinked to _ard/project_config/)`);
+      console.log('    └── OPENCODE.md -> AGENTICS.md');
+    }
+
+    console.log(chalk.bold('\nNext steps:'));
+    console.log('  1. Edit _ard/project_config/AGENTICS.md with your project context');
+    console.log('  2. Add project-specific commands to _ard/project_config/commands/');
+    console.log('  3. Start Claude Code and use /prime to explore your codebase');
+    console.log('');
+  }
+
+  _inferProjectName() {
+    const cwd = process.cwd();
+    return path.basename(cwd) || 'my-project';
+  }
+}