@siliconoid/agentkit 0.1.0

package/lib/utils.mjs

@@ -0,0 +1,296 @@
+import {
+  readFileSync, writeFileSync, mkdirSync, cpSync,
+  readdirSync, existsSync, statSync,
+} from 'fs'
+import { join, resolve, dirname, relative } from 'path'
+import { fileURLToPath } from 'url'
+import { validateConfig, normalizeConfig } from './schema.mjs'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const MARKERS = {
+  md: '<!-- AUTO-GENERATED by AgentKit -->',
+  toml: '# AUTO-GENERATED by AgentKit',
+  mdc: '<!-- AUTO-GENERATED by AgentKit -->',
+}
+
+export const CONFIG_FILE = '.ai/agentkit.json'
+
+export const PLATFORMS = [
+  { id: 'claude',       name: 'Claude Code',   rootFile: 'CLAUDE.md' },
+  { id: 'cursor',       name: 'Cursor',        rootFile: '.cursor/rules/project.mdc' },
+  { id: 'codex',        name: 'Codex',         rootFile: 'AGENTS.md' },
+  { id: 'gemini',       name: 'Gemini',        rootFile: 'GEMINI.md' },
+  { id: 'antigravity',  name: 'Antigravity',   rootFile: '.agent/rules.md' },
+  { id: 'windsurf',     name: 'Windsurf',      rootFile: '.windsurfrules' },
+]
+
+export const WORKFLOW_PACKS = [
+  {
+    id: 'bmad',
+    name: 'BMAD Method',
+    description: 'Full-process dev methodology (PM, Architect, Dev, QA agents, 46+ commands)',
+    platformMapping: {
+      claude:      { src: 'claude/commands_bmad',  dest: '.claude/commands/bmad' },
+      cursor:      { src: 'cursor/commands_bmad',  dest: '.cursor/commands/bmad' },
+      gemini:      { src: 'gemini/commands',        dest: '.gemini/commands' },
+      antigravity: { src: 'agent/workflows_bmad',   dest: '.agent/workflows/bmad' },
+    },
+    // Source files that command stubs reference via @_bmad/...
+    sourceDir: { src: '_bmad', dest: '_bmad' },
+  },
+]
+
+// Bundled skill bundles (multi-skill packs installed as a unit)
+export const SKILL_BUNDLES = [
+  {
+    id: 'superpowers',
+    name: 'Superpowers (by obra)',
+    description: 'TDD, code-review, brainstorming, systematic debugging — 14 composable skills',
+    license: 'MIT',
+    url: 'https://github.com/obra/superpowers',
+    templateDir: 'superpowers-skills',  // relative to templates/
+  },
+]
+
+// ---------------------------------------------------------------------------
+// YAML Parser (simple key: value, no nesting needed)
+// ---------------------------------------------------------------------------
+
+export function parseManifest(content) {
+  const result = {}
+  for (const line of content.split('\n')) {
+    const match = line.match(/^(\w[\w-]*):\s*(.+)$/)
+    if (match) {
+      let value = match[2].trim()
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1)
+      }
+      if (value === 'true') value = true
+      else if (value === 'false') value = false
+      result[match[1]] = value
+    }
+  }
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// Template Engine
+// ---------------------------------------------------------------------------
+
+/** Replace `{{var}}` placeholders in text */
+export function templateReplace(text, vars) {
+  return text.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    return vars[key] !== undefined ? vars[key] : `{{${key}}}`
+  })
+}
+
+// ---------------------------------------------------------------------------
+// File Utilities
+// ---------------------------------------------------------------------------
+
+export function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true })
+}
+
+/** Recursively copy a directory, applying template vars to file contents */
+export function copyDir(src, dest, vars = {}) {
+  ensureDir(dest)
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name)
+    const destPath = join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, vars)
+    } else {
+      const content = readFileSync(srcPath, 'utf8')
+      ensureDir(dirname(destPath))
+      writeFileSync(destPath, Object.keys(vars).length ? templateReplace(content, vars) : content)
+    }
+  }
+}
+
+/** Write file only if it does not already exist */
+export function writeIfNotExists(filePath, content) {
+  if (existsSync(filePath)) return false
+  ensureDir(dirname(filePath))
+  writeFileSync(filePath, content)
+  return true
+}
+
+/** Write file with auto-generated marker. Replaces only if marker is present (i.e., auto-generated). */
+export function writeWithMarker(filePath, content, marker) {
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf8')
+    if (!existing.startsWith(marker)) {
+      // File was manually edited — skip
+      return false
+    }
+  }
+  ensureDir(dirname(filePath))
+  writeFileSync(filePath, marker + '\n' + content)
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Project Discovery
+// ---------------------------------------------------------------------------
+
+/** Walk up from cwd to find a directory containing package.json or .git */
+export function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir)
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, 'package.json')) || existsSync(join(dir, '.git'))) {
+      return dir
+    }
+    dir = dirname(dir)
+  }
+  return process.cwd()
+}
+
+/** Detect which AI platforms are already configured in the project */
+export function detectPlatforms(projectRoot) {
+  return PLATFORMS
+    .filter(p => existsSync(join(projectRoot, p.rootFile)))
+    .map(p => p.id)
+}
+
+/** Discover all skills in .ai/skills/ */
+export function discoverSkills(projectRoot) {
+  const skillsDir = join(projectRoot, '.ai', 'skills')
+  if (!existsSync(skillsDir)) return []
+
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('_'))
+    .map(d => {
+      const dir = join(skillsDir, d.name)
+      const manifestPath = join(dir, 'manifest.yaml')
+      const skillMdPath = join(dir, 'skill.md')
+      if (!existsSync(manifestPath) || !existsSync(skillMdPath)) return null
+
+      const manifest = parseManifest(readFileSync(manifestPath, 'utf8'))
+      return { name: d.name, dir, manifest, skillMdPath }
+    })
+    .filter(Boolean)
+}
+
+/** Read .ai/agentkit.json config, or return null */
+export function readConfig(projectRoot) {
+  const configPath = join(projectRoot, CONFIG_FILE)
+  if (!existsSync(configPath)) return null
+
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'))
+
+    // Schema validation
+    const { valid, errors, warnings } = validateConfig(config)
+    if (!valid) {
+      console.error(`Invalid config in ${CONFIG_FILE}:`)
+      errors.forEach(e => console.error(`  ✘ ${e}`))
+      process.exit(1)
+    }
+    // Show warnings but don't fail
+    if (warnings.length > 0) {
+      warnings.forEach(w => console.warn(`  ⚠ ${w}`))
+    }
+
+    return normalizeConfig(config)
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      console.error(`Invalid JSON in ${CONFIG_FILE}: ${err.message}`)
+    } else {
+      console.error(`Error reading ${CONFIG_FILE}: ${err.message}`)
+    }
+    process.exit(1)
+  }
+}
+
+/** Write .ai/agentkit.json */
+export function writeConfig(projectRoot, config) {
+  const configPath = join(projectRoot, CONFIG_FILE)
+  ensureDir(dirname(configPath))
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+}
+
+/** Get the templates directory bundled with this CLI */
+export function getTemplatesDir() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', 'templates')
+}
+
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ * Handles both single-line and multi-line (indented continuation) values.
+ * Returns { name, description, ... } or null if no frontmatter.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/)
+  if (!match) return null
+
+  const result = {}
+  let currentKey = null
+  let currentValue = ''
+
+  for (const line of match[1].split('\n')) {
+    // New key: value line
+    const kvMatch = line.match(/^(\w[\w-]*):\s*(.*)$/)
+    if (kvMatch) {
+      // Save previous key
+      if (currentKey) {
+        result[currentKey] = cleanValue(currentValue.trim())
+      }
+      currentKey = kvMatch[1]
+      currentValue = kvMatch[2].trim()
+    } else if (currentKey && /^\s+/.test(line)) {
+      // Continuation line (indented)
+      currentValue += ' ' + line.trim()
+    }
+  }
+  // Save last key
+  if (currentKey) {
+    result[currentKey] = cleanValue(currentValue.trim())
+  }
+
+  return result
+}
+
+function cleanValue(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    value = value.slice(1, -1)
+  }
+  if (value === 'true') return true
+  if (value === 'false') return false
+  return value
+}
+
+/**
+ * Auto-discover available skill packs from templates/skills/.
+ * Each subdirectory with a SKILL.md (containing frontmatter) is a skill pack.
+ * Returns [{ id, name, description }]
+ */
+export function discoverSkillPacks() {
+  const skillsDir = join(getTemplatesDir(), 'skills')
+  if (!existsSync(skillsDir)) return []
+
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+    .map(d => {
+      const skillMd = join(skillsDir, d.name, 'SKILL.md')
+      if (!existsSync(skillMd)) return null
+
+      const meta = parseFrontmatter(readFileSync(skillMd, 'utf8'))
+      return {
+        id: d.name,
+        name: meta?.name || d.name,
+        description: meta?.description || '',
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.id.localeCompare(b.id))
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@siliconoid/agentkit",
+  "version": "0.1.0",
+  "description": "CLI tool to initialize and manage AI coding rules across multiple platforms",
+  "type": "module",
+  "bin": {
+    "agentkit": "bin/cli.mjs"
+  },
+  "main": "./lib/index.mjs",
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./cli": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicepkg/agentkit.git"
+  },
+  "homepage": "https://github.com/nicepkg/agentkit#readme",
+  "bugs": {
+    "url": "https://github.com/nicepkg/agentkit/issues"
+  },
+  "author": "superteam",
+  "keywords": [
+    "ai",
+    "coding-rules",
+    "claude",
+    "cursor",
+    "codex",
+    "gemini",
+    "windsurf",
+    "antigravity",
+    "agents-md",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.4.0",
+    "commander": "^13.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/templates/base/.ai/changelog/README.md

@@ -0,0 +1,21 @@
+# Changelog
+
+Monthly changelog files for **{{projectName}}**.
+
+## Format
+
+Each month gets its own file: `YYYY-MM.md`
+
+Entries follow this format:
+
+```markdown
+## [YYYY-MM-DD] <type>: <short description>
+
+- **What**: What was changed
+- **Why**: The motivation
+- **Impact**: What else is affected
+- **Gotchas**: Non-obvious side effects (if any)
+- **Related**: Links to ADRs, commits, issues
+```
+
+Type values: `feat`, `fix`, `refactor`, `perf`, `config`, `deps`

package/templates/base/.ai/decisions/README.md

@@ -0,0 +1,34 @@
+# Architecture Decision Records (ADR)
+
+This directory contains Architecture Decision Records for the {{projectName}} project.
+
+## What is an ADR?
+
+An ADR records an important architectural or technical decision, including the context, the decision itself, and its consequences. ADRs help AI agents and team members understand **why** decisions were made, not just what was done.
+
+## File Naming
+
+```
+NNN-short-description.md
+```
+
+- `NNN`: Three-digit sequential number (001, 002, ...)
+- `short-description`: Kebab-case summary of the decision
+
+## Template
+
+Use `.ai/decisions/_template.md` as the starting point for new ADRs.
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| proposed | Under discussion, not yet decided |
+| accepted | Decision made and in effect |
+| deprecated | Was accepted but no longer applies |
+| superseded | Replaced by a newer ADR (link to replacement) |
+
+## Index
+
+| # | Title | Status | Date |
+|---|-------|--------|------|

package/templates/base/.ai/decisions/_template.md

@@ -0,0 +1,29 @@
+# ADR-NNN: [Title]
+
+## Status
+proposed | accepted | deprecated | superseded by [ADR-XXX](XXX-title.md)
+
+## Date
+YYYY-MM-DD
+
+## Context
+<!-- What is the issue? What forces are at play? What is motivating this decision? -->
+
+## Decision
+<!-- What is the change that we're proposing and/or doing? -->
+
+## Consequences
+<!-- What becomes easier or more difficult because of this decision? -->
+
+### Positive
+- ...
+
+### Negative
+- ...
+
+### Risks
+- ...
+
+## Related
+<!-- Links to related ADRs, issues, PRs, or documentation -->
+- ...

package/templates/base/.ai/memory/debugging-patterns.md

@@ -0,0 +1,5 @@
+# Debugging Patterns
+
+Known debugging patterns and solutions for **{{projectName}}**.
+
+<!-- Add entries as non-obvious bugs are discovered and solved -->

package/templates/base/.ai/memory/known-issues.md

@@ -0,0 +1,5 @@
+# Known Issues
+
+Active known issues for **{{projectName}}**.
+
+<!-- Add entries when known issues are discovered. Remove when resolved. -->

package/templates/base/.ai/memory/refactoring-log.md

@@ -0,0 +1,5 @@
+# Refactoring Log
+
+Record of refactoring work in **{{projectName}}**.
+
+<!-- Add entries when significant refactoring is performed -->

package/templates/base/.ai/rules/01-project-overview.md

@@ -0,0 +1,23 @@
+# Project Overview
+
+**{{projectName}}** — {{projectDescription}}
+
+## Tech Stack
+
+| Category | Technology | Version |
+|----------|-----------|---------|
+| Framework | {{frameworkDisplay}} | {{frameworkVersion}} |
+| Language | {{primaryLanguage}} | {{typescriptVersion}} |
+| UI Components | {{uiLibrary}} | — |
+| State Management | {{stateManagement}} | — |
+| Styling | {{cssApproach}} | — |
+| HTTP Client | {{httpClient}} | — |
+| Testing | {{testingFramework}} | — |
+| Build Tool | {{buildTool}} | — |
+| Linter | {{linter}} | — |
+| Package Manager | {{packageManager}} | — |
+
+## Technology Constraints
+
+- List any version constraints or limitations here
+- Note which features are available or unavailable

package/templates/base/.ai/rules/02-architecture.md

@@ -0,0 +1,17 @@
+# Architecture
+
+## Overview
+
+Describe the high-level architecture of **{{projectName}}** here.
+
+## Request/Response Architecture
+
+Describe your API patterns, authentication, and data flow.
+
+## State Management
+
+Describe how application state is managed (Redux, Zustand, Context, etc.).
+
+## Component Layout System
+
+Describe your layout system and page structure.

package/templates/base/.ai/rules/03-coding-conventions.md

@@ -0,0 +1,26 @@
+# Coding Conventions
+
+## Path Aliases
+
+Define your path aliases (tsconfig paths, webpack aliases):
+
+```
+@/ → ./src/
+```
+
+**Always use path aliases instead of relative paths.**
+
+## API Request Pattern
+
+Describe your HTTP client usage and patterns.
+
+## Internationalization
+
+If applicable, describe your i18n setup and conventions.
+
+## Import Order
+
+1. External dependencies
+2. Internal modules (path aliases)
+3. Relative imports
+4. Styles

package/templates/base/.ai/rules/04-directory-structure.md

@@ -0,0 +1,20 @@
+# Directory Structure
+
+```
+{{projectName}}/
+├── src/
+│   ├── components/         # React/Vue components
+│   ├── lib/                # Utility libraries
+│   ├── pages/              # Pages / routes
+│   └── styles/             # Global styles
+├── public/                 # Static assets
+└── ...
+```
+
+> Update this tree to match your actual project structure.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/...` | — |

package/templates/base/.ai/rules/05-environment.md

@@ -0,0 +1,29 @@
+# Environment & Commands
+
+## Development Commands
+
+```bash
+npm run dev          # Development server
+npm run build        # Production build
+npm run start        # Production server
+npm run lint         # Lint code
+npm run test         # Run tests
+```
+
+## Environment Variables
+
+### Required
+
+```bash
+# Add your required environment variables here
+```
+
+### Optional
+
+```bash
+# Add your optional environment variables here
+```
+
+## Critical Notes
+
+- List any important build or runtime notes here

package/templates/base/.ai/rules/06-typescript.md

@@ -0,0 +1,32 @@
+# TypeScript
+
+## Compiler Configuration
+
+Key `tsconfig.json` settings for this project:
+
+| Setting | Value | Notes |
+|---------|-------|-------|
+| `strict` | `true` | All strict checks enabled |
+| `target` | `ES2020` | — |
+
+## Strict Rules
+
+- **Strict mode** is enabled — respect all strict checks.
+- Prefer `interface` for object shapes; use `type` for unions, intersections, and mapped types.
+- **Minimize `any`** — use `unknown` and narrow with type guards.
+- Always type function parameters and return types for exported functions.
+- Use `as const` for literal tuples and fixed arrays.
+- No `// @ts-ignore` — use `// @ts-expect-error` with an explanation comment if absolutely necessary.
+
+## Interface vs Type
+
+| Use Case | Keyword |
+|----------|---------|
+| Object shapes, component props | `interface` |
+| Union types, mapped types, primitives | `type` |
+
+## `any` Strategy
+
+- **New code**: Never use `any`. Use `unknown`, generics, or specific types.
+- **Legacy code**: Tolerate existing `any` but do not expand its scope.
+- **Never** add new `any` just to silence errors — fix the type instead.

package/templates/base/.ai/rules/07-react.md

@@ -0,0 +1,34 @@
+# React
+
+## Component Structure
+
+Each component lives in its own directory:
+
+```
+components/common/my-component/
+├── index.tsx              # Component implementation
+├── index.module.scss      # Scoped styles
+└── (optional sub-files)
+```
+
+## Function Components Only
+
+Use function components for all new code. Do not introduce new class components.
+
+## Props Handling
+
+Destructure props in the function signature. Use default parameter values.
+
+## Event Handler Naming
+
+| Type | Prefix | Example |
+|------|--------|---------|
+| Internal handler | `handle` | `handleClick`, `handleSubmit` |
+| Prop callback | `on` | `onClick`, `onSubmit` |
+
+## Hooks Best Practices
+
+- **One effect per concern** — separate data fetching, event listeners, and timers
+- **Always clean up** — return a cleanup function for subscriptions, timers, and listeners
+- `useCallback` — wrap callbacks passed to child components
+- `useMemo` — use for computationally expensive derived values

package/templates/base/.ai/rules/08-styling.md

@@ -0,0 +1,38 @@
+# Styling
+
+## CSS Modules (Primary Method)
+
+All component styles use CSS Modules:
+
+```typescript
+import styles from './index.module.scss'
+```
+
+### Class Name Conventions
+
+Use **camelCase** for CSS class names:
+
+```scss
+.container { ... }
+.headerWrapper { ... }
+.isActive { ... }
+```
+
+## CSS Custom Properties (Theming)
+
+Use CSS custom properties for theming values:
+
+```scss
+.button {
+  color: var(--primary-color);
+  background: var(--bg-color);
+}
+```
+
+## Inline Styles
+
+Only use inline styles for values computed at runtime.
+
+## Responsive Breakpoints
+
+Common breakpoints: `768px` (tablet), `1200px` (desktop).