@siliconoid/agentkit 0.1.0

package/lib/adapters/gemini.mjs

@@ -0,0 +1,69 @@
+import { join } from 'path'
+import { MARKERS } from '../utils.mjs'
+
+export const id = 'gemini'
+export const name = 'Gemini'
+
+export function getOutputPaths(projectRoot) {
+  return {
+    rootDoc: join(projectRoot, 'GEMINI.md'),
+    skillsDir: join(projectRoot, '.gemini', 'skills'),
+    commandsDir: join(projectRoot, '.gemini', 'commands'),
+  }
+}
+
+export function generateRootDoc(vars) {
+  return `# GEMINI.md
+
+> Project instructions for Google Gemini Code Assist / Gemini CLI.
+
+**${vars.projectName}** — ${vars.projectDescription || 'A software project.'}
+
+## Project Rules
+
+@.ai/rules/*.md
+
+## Architecture Decisions & Memory
+
+- \`.ai/decisions/\` — Architecture Decision Records (ADRs) with context and rationale
+- \`.ai/changelog/\` — Monthly change logs with context, reasoning, and impact
+- \`.ai/skills/\` — Portable skill definitions — read and execute \`.ai/skills/<name>/skill.md\` when triggered
+- \`.ai/memory/\` — Shared memory files (debugging patterns, known issues, refactoring log)
+- \`.specs/\` — Epics, stories, tasks, and completed archive
+`
+}
+
+export function generateSkillStub(manifest, vars = {}) {
+  const lines = [
+    '---',
+    `name: ${manifest.name}`,
+    `description: ${manifest.description}`,
+    '---',
+    '',
+    `# ${manifest.name}`,
+    '',
+    `Read and follow the skill definition at \`.ai/skills/${manifest.name}/skill.md\` exactly.`,
+    '',
+    "The user's argument (if any) provides context for this skill invocation.",
+    '',
+  ]
+  return lines.join('\n')
+}
+
+export function generateCommand(manifest) {
+  const escapedDesc = manifest.description.replace(/"/g, '\\"')
+  return `description = "${escapedDesc}"
+prompt = """
+Read and follow the skill definition at \`.ai/skills/${manifest.name}/skill.md\` exactly.
+
+Execute all steps defined in that file. The user's input (if any) is provided below.
+"""
+`
+}
+
+export function generateRules() {
+  return null // Gemini uses @file references in GEMINI.md
+}
+
+export const marker = MARKERS.md
+export const commandMarker = MARKERS.toml

package/lib/adapters/windsurf.mjs

@@ -0,0 +1,65 @@
+import { join } from 'path'
+import { readFileSync, readdirSync, existsSync } from 'fs'
+
+export const id = 'windsurf'
+export const name = 'Windsurf'
+
+export function getOutputPaths(projectRoot) {
+  return {
+    rootDoc: join(projectRoot, '.windsurfrules'),
+  }
+}
+
+export function generateRootDoc(vars) {
+  return `# ${vars.projectName}
+
+${vars.projectDescription || 'A software project.'}
+
+## Project Rules
+
+All project rules are maintained in \`.ai/rules/\`. Read all files in that directory for complete coding conventions, architecture, and workflow documentation.
+
+## Architecture Decisions & Memory
+
+- \`.ai/decisions/\` — ADRs with context and rationale
+- \`.ai/changelog/\` — Monthly change logs
+- \`.ai/skills/\` — Portable skill definitions
+- \`.ai/memory/\` — Shared memory files
+- \`.specs/\` — Epics, stories, tasks, and completed archive
+`
+}
+
+/**
+ * Build the full .windsurfrules by concatenating all rule files.
+ * Called during sync to produce a single merged file.
+ */
+export function generateMergedRules(projectRoot, vars) {
+  const rulesDir = join(projectRoot, '.ai', 'rules')
+  const header = `# ${vars.projectName}\n\n${vars.projectDescription || 'A software project.'}\n\n`
+
+  if (!existsSync(rulesDir)) return header
+
+  const files = readdirSync(rulesDir)
+    .filter(f => f.endsWith('.md') && !f.startsWith('_'))
+    .sort()
+
+  const sections = files.map(f => {
+    return readFileSync(join(rulesDir, f), 'utf8').trim()
+  })
+
+  return header + sections.join('\n\n---\n\n') + '\n'
+}
+
+export function generateSkillStub() {
+  return null // Windsurf doesn't support skills
+}
+
+export function generateCommand() {
+  return null // Windsurf doesn't support commands
+}
+
+export function generateRules() {
+  return null // Windsurf uses single .windsurfrules
+}
+
+export const marker = '# AUTO-GENERATED by AgentKit'

package/lib/commands/add-platform.mjs

@@ -0,0 +1,73 @@
+import { join } from 'path'
+import {
+  findProjectRoot, readConfig, writeConfig, PLATFORMS,
+} from '../utils.mjs'
+import { scaffoldPlatforms, scaffoldWorkflows, scaffoldSkills } from '../scaffold.mjs'
+import { runSync } from './sync.mjs'
+import log from '../log.mjs'
+
+const VALID_IDS = PLATFORMS.map(p => p.id)
+
+export async function runAddPlatform(platformId) {
+  if (!VALID_IDS.includes(platformId)) {
+    log.error(`Unknown platform "${platformId}". Valid options: ${VALID_IDS.join(', ')}`)
+    process.exit(1)
+  }
+
+  try {
+    const projectRoot = findProjectRoot()
+    const config = readConfig(projectRoot)
+
+    if (!config) {
+      log.error('No .ai/agentkit.json found. Run `agentkit init` first.')
+      process.exit(1)
+    }
+
+    if (config.platforms.includes(platformId)) {
+      log.warn(`Platform "${platformId}" is already configured.`)
+      return
+    }
+
+    const vars = {
+      projectName: config.projectName || 'project',
+      projectDescription: config.projectDescription || '',
+      framework: config.framework || 'custom',
+    }
+
+    // Add platform
+    config.platforms.push(platformId)
+
+    // Generate root doc
+    log.header(`Adding ${platformId}...`)
+    const platFiles = await scaffoldPlatforms(projectRoot, [platformId], vars)
+    platFiles.forEach(f => log.created(f))
+
+    // Install workflow packs if enabled
+    if (config.workflowPacks?.length > 0) {
+      const wfFiles = scaffoldWorkflows(projectRoot, [platformId], config.workflowPacks)
+      if (wfFiles.length > 0) {
+        log.success(`  ${wfFiles.length} workflow command files installed`)
+      }
+    }
+
+    // Install skill packs if any
+    if (config.skillPacks?.length > 0) {
+      const skillFiles = scaffoldSkills(projectRoot, [platformId], config.skillPacks)
+      if (skillFiles.length > 0) {
+        log.success(`  ${skillFiles.length} skill pack files installed`)
+      }
+    }
+
+    // Sync portable skills
+    await runSync({ _projectRoot: projectRoot, _platforms: [platformId], _vars: vars })
+
+    // Update config
+    writeConfig(projectRoot, config)
+    log.success(`\nPlatform "${platformId}" added and synced.`)
+    log.plain('')
+  } catch (err) {
+    log.error(`Add platform failed: ${err.message}`)
+    log.verbose(err.stack)
+    process.exit(1)
+  }
+}

package/lib/commands/add-skill-pack.mjs

@@ -0,0 +1,49 @@
+import {
+  findProjectRoot, readConfig, writeConfig, discoverSkillPacks,
+} from '../utils.mjs'
+import { scaffoldSkills } from '../scaffold.mjs'
+import log from '../log.mjs'
+
+export async function runAddSkillPack(packId) {
+  const available = discoverSkillPacks()
+  const validIds = available.map(p => p.id)
+
+  if (!validIds.includes(packId)) {
+    log.error(`Unknown skill pack "${packId}". Available: ${validIds.join(', ')}`)
+    process.exit(1)
+  }
+
+  try {
+    const projectRoot = findProjectRoot()
+    const config = readConfig(projectRoot)
+
+    if (!config) {
+      log.error('No .ai/agentkit.json found. Run `agentkit init` first.')
+      process.exit(1)
+    }
+
+    if (config.skillPacks.includes(packId)) {
+      log.warn(`Skill pack "${packId}" is already installed.`)
+      return
+    }
+
+    // Add to config
+    config.skillPacks.push(packId)
+
+    // Install skill pack files for all configured platforms
+    log.header(`Adding skill pack: ${packId}...`)
+    const skillFiles = scaffoldSkills(projectRoot, config.platforms, [packId])
+    if (skillFiles.length > 0) {
+      log.success(`  ${skillFiles.length} skill file(s) installed`)
+    }
+
+    // Update config
+    writeConfig(projectRoot, config)
+    log.success(`\nSkill pack "${packId}" added.`)
+    log.plain('')
+  } catch (err) {
+    log.error(`Add skill pack failed: ${err.message}`)
+    log.verbose(err.stack)
+    process.exit(1)
+  }
+}

package/lib/commands/add-skill.mjs

@@ -0,0 +1,78 @@
+import { join } from 'path'
+import { existsSync, writeFileSync } from 'fs'
+import { findProjectRoot, ensureDir, readConfig } from '../utils.mjs'
+import { runSync } from './sync.mjs'
+import log from '../log.mjs'
+
+export async function runAddSkill(name, opts = {}) {
+  // Validate skill name
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
+    log.error(`Invalid skill name "${name}". Use lowercase letters, numbers, and hyphens (e.g., "my-skill").`)
+    process.exit(1)
+  }
+
+  try {
+    const projectRoot = findProjectRoot()
+    const skillDir = join(projectRoot, '.ai', 'skills', name)
+
+    if (existsSync(skillDir)) {
+      log.error(`Skill "${name}" already exists at .ai/skills/${name}/`)
+      process.exit(1)
+    }
+
+    const description = opts.description || `Description for ${name} skill.`
+
+    // Create manifest.yaml
+    ensureDir(skillDir)
+
+    const manifest = `name: ${name}
+description: ${description}
+user-invocable: true
+argument-hint: "[optional: context for this skill]"
+`
+
+    const skillMd = `# ${name[0].toUpperCase() + name.slice(1)} Workflow
+
+${description}
+
+## When to Use
+
+- TODO: describe when this skill should be triggered
+
+## Workflow Steps
+
+### Step 1: Gather Context
+
+Analyze the current conversation and user input to understand the task.
+
+### Step 2: Execute
+
+TODO: define the steps this skill performs.
+
+### Step 3: Confirm
+
+Output a brief summary of what was done.
+`
+
+    writeFileSync(join(skillDir, 'manifest.yaml'), manifest)
+    writeFileSync(join(skillDir, 'skill.md'), skillMd)
+
+    log.header('Created skill scaffold:')
+    log.created(`.ai/skills/${name}/manifest.yaml`)
+    log.created(`.ai/skills/${name}/skill.md`)
+
+    // Auto-sync if config exists
+    const config = readConfig(projectRoot)
+    if (config) {
+      log.header('Syncing to platforms...')
+      await runSync({ _projectRoot: projectRoot })
+    } else {
+      log.plain('\nRun `npx agentkit sync` to generate platform adapters.')
+    }
+    log.plain('')
+  } catch (err) {
+    log.error(`Add skill failed: ${err.message}`)
+    log.verbose(err.stack)
+    process.exit(1)
+  }
+}

package/lib/commands/diff.mjs

@@ -0,0 +1,110 @@
+import { join } from 'path'
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { findProjectRoot, readConfig, getTemplatesDir } from '../utils.mjs'
+import log from '../log.mjs'
+import pc from 'picocolors'
+
+/**
+ * Compare local .ai/rules/ files against template versions.
+ * Shows which rules have been customized vs unchanged.
+ */
+export async function runDiff() {
+  const projectRoot = findProjectRoot()
+  const config = readConfig(projectRoot)
+
+  if (!config) {
+    log.error('No .ai/agentkit.json found. Run `agentkit init` first.')
+    process.exit(1)
+  }
+
+  const rulesDir = join(projectRoot, '.ai', 'rules')
+  if (!existsSync(rulesDir)) {
+    log.error('.ai/rules/ directory not found.')
+    process.exit(1)
+  }
+
+  const templatesDir = getTemplatesDir()
+  const framework = config.framework || 'custom'
+
+  log.header('Rule Diff: local vs template')
+  log.plain('')
+
+  const ruleFiles = readdirSync(rulesDir).filter(f => f.endsWith('.md')).sort()
+  let customized = 0
+  let matched = 0
+  let localOnly = 0
+
+  for (const file of ruleFiles) {
+    const localPath = join(rulesDir, file)
+    const localContent = readFileSync(localPath, 'utf8')
+    const localLines = localContent.split('\n')
+
+    // Try to find template: framework-specific first, then base
+    const templateContent = getTemplateContent(templatesDir, framework, file)
+
+    if (!templateContent) {
+      log.plain(`  ${pc.blue('+')} ${file.padEnd(35)} ${pc.blue('local only (no template)')}`)
+      localOnly++
+      continue
+    }
+
+    const templateLines = templateContent.split('\n')
+    const diffLines = countDiffLines(localLines, templateLines)
+
+    if (diffLines === 0) {
+      log.plain(`  ${pc.green('=')} ${file.padEnd(35)} ${pc.green('matches template')}`)
+      matched++
+    } else {
+      log.plain(`  ${pc.yellow('~')} ${file.padEnd(35)} ${pc.yellow(`customized (${diffLines} lines differ)`)}`)
+      customized++
+    }
+  }
+
+  // Summary
+  log.plain('')
+  const parts = []
+  if (customized > 0) parts.push(pc.yellow(`${customized} customized`))
+  if (matched > 0) parts.push(pc.green(`${matched} match template`))
+  if (localOnly > 0) parts.push(pc.blue(`${localOnly} local only`))
+  log.plain(`  ${parts.join(', ')}`)
+  log.plain('')
+}
+
+/**
+ * Get template content for a rule file.
+ * Checks framework-specific template first, then base template.
+ */
+function getTemplateContent(templatesDir, framework, fileName) {
+  // Check framework-specific template first
+  if (framework && framework !== 'custom') {
+    const fwPath = join(templatesDir, 'frameworks', framework, '.ai', 'rules', fileName)
+    if (existsSync(fwPath)) {
+      return readFileSync(fwPath, 'utf8')
+    }
+  }
+
+  // Fall back to base template
+  const basePath = join(templatesDir, 'base', '.ai', 'rules', fileName)
+  if (existsSync(basePath)) {
+    return readFileSync(basePath, 'utf8')
+  }
+
+  return null
+}
+
+/**
+ * Count the number of lines that differ between two sets of lines.
+ * Simple line-by-line comparison.
+ */
+function countDiffLines(localLines, templateLines) {
+  const maxLen = Math.max(localLines.length, templateLines.length)
+  let diffCount = 0
+
+  for (let i = 0; i < maxLen; i++) {
+    const local = localLines[i] || ''
+    const template = templateLines[i] || ''
+    if (local !== template) diffCount++
+  }
+
+  return diffCount
+}

package/lib/commands/doctor.mjs

@@ -0,0 +1,196 @@
+import { join } from 'path'
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { findProjectRoot, readConfig, PLATFORMS, WORKFLOW_PACKS, discoverSkills } from '../utils.mjs'
+import log from '../log.mjs'
+import pc from 'picocolors'
+
+export async function runDoctor(opts = {}) {
+  const projectRoot = findProjectRoot()
+  const issues = []
+  const ok = []
+
+  log.info('\nRunning diagnostics...\n')
+
+  // 1. Check config file
+  const config = readConfig(projectRoot)
+  if (!config) {
+    log.error('No .ai/agentkit.json found. Run `agentkit init` first.')
+    process.exit(1)
+  }
+  ok.push('Config file (.ai/agentkit.json) exists and is valid')
+
+  // 2. Check .ai/rules/ directory
+  const rulesDir = join(projectRoot, '.ai', 'rules')
+  if (existsSync(rulesDir)) {
+    const ruleFiles = readdirSync(rulesDir).filter(f => f.endsWith('.md'))
+    if (ruleFiles.length === 0) {
+      issues.push('.ai/rules/ directory is empty — no rule files found')
+    } else {
+      ok.push(`.ai/rules/ has ${ruleFiles.length} rule file(s)`)
+    }
+  } else {
+    issues.push('.ai/rules/ directory missing — run `agentkit update`')
+  }
+
+  // 3. Check platform root files
+  for (const platformId of config.platforms) {
+    const platform = PLATFORMS.find(p => p.id === platformId)
+    if (!platform) {
+      issues.push(`Unknown platform "${platformId}" in config`)
+      continue
+    }
+    if (existsSync(join(projectRoot, platform.rootFile))) {
+      ok.push(`${platform.name} root file (${platform.rootFile}) exists`)
+    } else {
+      issues.push(`${platform.name} root file (${platform.rootFile}) missing — run \`agentkit update\``)
+    }
+  }
+
+  // 4. Check skills
+  const skills = discoverSkills(projectRoot)
+  if (skills.length > 0) {
+    ok.push(`${skills.length} portable skill(s) found`)
+
+    // Verify each skill has both manifest.yaml and skill.md
+    for (const skill of skills) {
+      const manifestPath = join(skill.dir, 'manifest.yaml')
+      const skillMdPath = join(skill.dir, 'skill.md')
+      if (!existsSync(manifestPath)) {
+        issues.push(`Skill "${skill.name}" is missing manifest.yaml`)
+      }
+      if (!existsSync(skillMdPath)) {
+        issues.push(`Skill "${skill.name}" is missing skill.md`)
+      }
+    }
+  }
+
+  // 5. Check .ai/ auxiliary dirs
+  const auxDirs = ['decisions', 'changelog', 'memory']
+  for (const dir of auxDirs) {
+    if (existsSync(join(projectRoot, '.ai', dir))) {
+      ok.push(`.ai/${dir}/ exists`)
+    } else {
+      issues.push(`.ai/${dir}/ directory missing`)
+    }
+  }
+
+  // 6. Check .specs/
+  if (existsSync(join(projectRoot, '.specs'))) {
+    ok.push('.specs/ directory exists')
+  } else {
+    issues.push('.specs/ directory missing')
+  }
+
+  // 7. Check framework template exists
+  if (config.framework && config.framework !== 'custom') {
+    ok.push(`Framework: ${config.framework}`)
+  }
+
+  // 8. Check workflow packs
+  if (config.workflowPacks?.length > 0) {
+    for (const packId of config.workflowPacks) {
+      const pack = WORKFLOW_PACKS.find(w => w.id === packId)
+      if (!pack) {
+        issues.push(`Unknown workflow pack "${packId}" in config`)
+      } else {
+        ok.push(`Workflow pack: ${pack.name}`)
+      }
+    }
+  }
+
+  // Deep checks (--deep flag)
+  if (opts.deep) {
+    // 9. Check all 13 expected rule files exist
+    const expectedRules = Array.from({ length: 13 }, (_, i) => {
+      const num = String(i + 1).padStart(2, '0')
+      return `${num}-`
+    })
+    if (existsSync(rulesDir)) {
+      const ruleFiles = readdirSync(rulesDir).filter(f => f.endsWith('.md'))
+      for (const prefix of expectedRules) {
+        const found = ruleFiles.some(f => f.startsWith(prefix))
+        if (found) {
+          ok.push(`Rule ${prefix}*.md exists`)
+        } else {
+          issues.push(`Missing rule file with prefix ${prefix} (expected 01- through 13-)`)
+        }
+      }
+    }
+
+    // 10. Check for unreplaced {{variable}} placeholders in rule files
+    if (existsSync(rulesDir)) {
+      const ruleFiles = readdirSync(rulesDir).filter(f => f.endsWith('.md'))
+      for (const file of ruleFiles) {
+        const content = readFileSync(join(rulesDir, file), 'utf8')
+        const placeholders = content.match(/\{\{\w+\}\}/g)
+        if (placeholders) {
+          const unique = [...new Set(placeholders)]
+          issues.push(`${file} has unreplaced placeholders: ${unique.join(', ')}`)
+        }
+      }
+    }
+
+    // 11. Check root doc references .ai/rules/
+    for (const platformId of config.platforms) {
+      const platform = PLATFORMS.find(p => p.id === platformId)
+      if (!platform) continue
+      const rootFilePath = join(projectRoot, platform.rootFile)
+      if (existsSync(rootFilePath)) {
+        const content = readFileSync(rootFilePath, 'utf8')
+        if (content.includes('.ai/rules/') || content.includes('.ai/rules\\')) {
+          ok.push(`${platform.name} root doc references .ai/rules/`)
+        } else {
+          issues.push(`${platform.name} root doc (${platform.rootFile}) does not reference .ai/rules/`)
+        }
+      }
+    }
+
+    // 12. Check skill sync status
+    const skills = discoverSkills(projectRoot)
+    if (skills.length > 0) {
+      for (const platformId of config.platforms) {
+        const skillDirMap = {
+          claude: '.claude/skills',
+          codex: '.codex/skills',
+          gemini: '.gemini/skills',
+          antigravity: '.agent/skills',
+        }
+        const platformSkillDir = skillDirMap[platformId]
+        if (!platformSkillDir) continue
+
+        const fullDir = join(projectRoot, platformSkillDir)
+        if (existsSync(fullDir)) {
+          const platformSkills = readdirSync(fullDir, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name)
+          const missing = skills.filter(s => !platformSkills.includes(s.name))
+          if (missing.length > 0) {
+            issues.push(`${platformId}: skills not synced: ${missing.map(s => s.name).join(', ')} — run \`agentkit sync\``)
+          } else {
+            ok.push(`${platformId}: all skills synced`)
+          }
+        }
+      }
+    }
+  }
+
+  // Report
+  log.header('Results')
+
+  for (const item of ok) {
+    log.plain(`  ${pc.green('✓')} ${item}`)
+  }
+
+  if (issues.length > 0) {
+    log.plain('')
+    for (const issue of issues) {
+      log.plain(`  ${pc.red('✘')} ${issue}`)
+    }
+    log.plain(`\n${pc.yellow(`Found ${issues.length} issue(s). Run suggested commands to fix.`)}`)
+  } else {
+    log.plain(`\n${pc.green('No issues found. Everything looks good!')}`)
+  }
+
+  log.plain('')
+  process.exit(issues.length > 0 ? 1 : 0)
+}