@siliconoid/agentkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 superteam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# AgentKit
+
+CLI tool to initialize and manage AI coding rules across 6 platforms — one source of truth, all agents aligned.
+
+## Supported Platforms
+
+| Platform | Root File | Skills | Commands |
+|----------|-----------|--------|----------|
+| Claude Code | `CLAUDE.md` | `.claude/skills/` | `.claude/commands/` |
+| Cursor | `.cursor/rules/project.mdc` | — | `.cursor/commands/` |
+| Codex | `AGENTS.md` | `.codex/skills/` | — |
+| Gemini | `GEMINI.md` | `.gemini/skills/` | `.gemini/commands/*.toml` |
+| Antigravity | `.agent/rules.md` | `.agent/skills/` | `.agent/workflows/` |
+| Windsurf | `.windsurfrules` | — | — |
+
+## Quick Start
+
+```bash
+# Interactive setup (auto-detects project name, framework, existing platforms)
+npx agentkit init
+
+# Use all defaults (6 platforms + all workflow packs + all skill packs)
+npx agentkit init --yes
+
+# Preview what would be created
+npx agentkit init --yes --dry-run
+```
+
+## Commands
+
+### `init`
+
+Initialize AI project rules in the current directory.
+
+```bash
+npx agentkit init [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-y, --yes` | Use defaults without prompting |
+| `--force` | Re-initialize even if already configured |
+| `--dry-run` | Preview what would be created without writing files |
+
+Auto-detects from `package.json` and project structure:
+- **Project name** and **description**
+- **Framework** (Next.js Pages/App, React SPA, Vue, Node.js)
+- **Existing platforms** (scans for CLAUDE.md, .cursorrules, etc.)
+
+### `sync`
+
+Sync portable skills (`.ai/skills/`) to all configured platform adapters.
+
+```bash
+npx agentkit sync [--dry] [--clean]
+```
+
+- `--dry` — preview changes without writing files
+- `--clean` — remove auto-generated skill stubs before re-syncing
+
+### `add-skill`
+
+Create a new skill scaffold in `.ai/skills/`.
+
+```bash
+npx agentkit add-skill <name> [-d "description"]
+```
+
+Validates name (lowercase, hyphens, e.g. `my-skill`). Creates `manifest.yaml` + `skill.md`, then auto-syncs.
+
+### `update`
+
+Non-destructively update templates (only adds missing files).
+
+```bash
+npx agentkit update [--force]
+```
+
+- `--force` — overwrite existing files with latest templates
+
+### `list`
+
+Show current project configuration and installed components.
+
+```bash
+npx agentkit list    # or: npx agentkit ls
+```
+
+### `add-skill-pack`
+
+Add a skill pack to an existing project.
+
+```bash
+npx agentkit add-skill-pack <pack>
+# e.g.: npx agentkit add-skill-pack frontend-design
+```
+
+Lists available packs if given an invalid name. Installs pack files to all configured platforms.
+
+### `add-platform`
+
+Add a new AI platform to an existing project.
+
+```bash
+npx agentkit add-platform <platform>
+# e.g.: npx agentkit add-platform codex
+```
+
+Generates root doc, installs workflow packs and skill packs, syncs skills.
+
+### `doctor`
+
+Check project configuration for issues.
+
+```bash
+npx agentkit doctor
+```
+
+Validates: config file, rule files, platform root docs, skills, auxiliary directories.
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--verbose` | Show detailed output (file-level details) |
+| `--quiet` | Suppress non-essential output |
+| `-V, --version` | Show version number |
+
+## Generated Structure
+
+```
+your-project/
+├── .ai/                         # Single source of truth
+│   ├── rules/                   # 13 rule files
+│   │   ├── 01-project-overview.md
+│   │   ├── 02-architecture.md
+│   │   ├── 03-coding-conventions.md
+│   │   ├── 04-directory-structure.md
+│   │   ├── 05-environment.md
+│   │   ├── 06-typescript.md
+│   │   ├── 07-react.md
+│   │   ├── 08-styling.md
+│   │   ├── 09-naming.md
+│   │   ├── 10-git-workflow.md
+│   │   ├── 11-testing.md
+│   │   ├── 12-forbidden-patterns.md
+│   │   └── 13-ai-agent.md
+│   ├── skills/                  # Portable skill definitions
+│   │   ├── adr/                 # Architecture Decision Records
+│   │   ├── devlog/              # AI-optimized changelog
+│   │   └── wrap-up/             # End-of-task memory sync
+│   ├── decisions/               # ADRs
+│   ├── changelog/               # Monthly change logs
+│   ├── memory/                  # Debugging patterns, known issues
+│   ├── scripts/                 # Sync helper script
+│   └── agentkit.json      # CLI configuration
+├── .specs/                      # Epics, stories, tasks
+├── CLAUDE.md                    # Claude Code entry point
+├── AGENTS.md                    # Codex entry point
+├── GEMINI.md                    # Gemini entry point
+├── .windsurfrules               # Windsurf (merged rules)
+├── .cursor/rules/project.mdc   # Cursor entry point
+├── .agent/rules.md              # Antigravity entry point
+├── .claude/
+│   ├── skills/                  # 9 skills (3 portable + 6 packs)
+│   └── commands/bmad/           # BMAD workflow commands
+├── .codex/skills/
+├── .gemini/skills/ & commands/
+└── .agent/skills/ & workflows/
+```
+
+## Frameworks
+
+Framework-specific rule overrides are applied during `init`:
+
+| Framework | Overrides |
+|-----------|-----------|
+| **React SPA** | Vite + React 18 + Ant Design, PascalCase components, Vitest + MSW, Zustand, forbidden patterns |
+| **Next.js (Pages Router)** | Pages Router patterns, `getServerSideProps`, SSR conventions |
+| **Next.js (App Router)** | Server Components, `'use client'`, Server Actions, RSC patterns |
+| **Vue** | Composition API, `<script setup>`, Pinia, Vue Router, composables |
+| **Node.js** | Backend module structure, API design, validation, logging |
+| **Custom** | Generic base templates only |
+
+## Skill Packs
+
+Curated skill packs auto-discovered from `templates/skills/`. Multi-select during `init`, or add later with `add-skill-pack`.
+
+Installed to platforms that support skills (Claude, Codex, Gemini, Antigravity):
+
+| Pack | Description |
+|------|-------------|
+| `frontend-design` | Frontend design quality guidelines |
+| `next-best-practices` | Next.js best practices (Vercel, 20 docs) |
+| `security-best-practices` | Language/framework security reviews (13 docs) |
+| `vercel-composition-patterns` | React composition patterns (10 docs) |
+| `vercel-react-best-practices` | React & Next.js performance (60 docs) |
+| `web-design-guidelines` | Web Interface Guidelines compliance |
+
+### Adding a new skill pack
+
+Drop a directory in `templates/skills/<pack-name>/` with a `SKILL.md` containing YAML frontmatter:
+
+```markdown
+---
+name: my-new-pack
+description: What this skill pack does
+---
+
+Skill content here...
+```
+
+The CLI auto-discovers it — no code changes needed.
+
+## Workflow Packs
+
+Workflow packs provide agent commands and development workflows. Multi-select during `init`, or skip entirely.
+
+| Pack | Description | Best For |
+|------|-------------|----------|
+| **BMAD Method** | Full-process dev methodology (PM, Architect, Dev, QA agents, 46+ commands) | New projects, architecture design, PRDs, sprint planning |
+
+Installed per platform:
+- **Claude / Cursor**: `.claude/commands/bmad/` / `.cursor/commands/bmad/`
+- **Gemini**: `.gemini/commands/`
+- **Antigravity**: `.agent/workflows/bmad/`
+
+### Recommended External Plugins
+
+These are installed separately through their native platform mechanisms:
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **Superpowers** (by obra) | TDD, code-review, quality gates, brainstorming — 14 composable skills | `/plugin install superpowers@superpowers-marketplace` |
+- **Antigravity**: `.agent/workflows/<pack>/`
+
+## How It Works
+
+1. **`.ai/rules/`** is the single source of truth for all project rules
+2. **Root docs** (`CLAUDE.md`, `AGENTS.md`, etc.) reference `.ai/rules/` via `@` includes or direct instructions
+3. **`.ai/skills/`** defines portable skills with `manifest.yaml` + `skill.md`
+4. **`sync`** reads skills and generates platform-specific adapters (SKILL.md for Claude, .toml for Gemini, etc.)
+5. **Windsurf** gets a merged `.windsurfrules` file since it doesn't support directory references
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
+
+const program = new Command()
+
+program
+  .name('agentkit')
+  .description('Initialize and manage AI coding rules across multiple platforms')
+  .version(pkg.version)
+  .option('--verbose', 'Show detailed output')
+  .option('--quiet', 'Suppress non-essential output')
+  .hook('preAction', async (thisCommand) => {
+    const { setVerbosity } = await import('../lib/log.mjs')
+    const opts = thisCommand.opts()
+    if (opts.quiet) setVerbosity(0)
+    else if (opts.verbose) setVerbosity(2)
+  })
+
+program
+  .command('init')
+  .description('Initialize AI project rules in the current directory')
+  .option('-y, --yes', 'Use defaults without prompting')
+  .option('--smart', 'Zero-question fully auto-detected init')
+  .option('--minimal', 'Minimal init (core rules only, no skills/workflows)')
+  .option('--force', 'Re-initialize even if already configured')
+  .option('--dry-run', 'Preview what would be created without writing files')
+  .action(async (opts) => {
+    const { runInit } = await import('../lib/commands/init.mjs')
+    await runInit(opts)
+  })
+
+program
+  .command('sync')
+  .description('Sync skills to all configured platform adapters')
+  .option('--clean', 'Remove auto-generated files before syncing')
+  .option('--dry', 'Preview changes without writing files')
+  .action(async (opts) => {
+    const { runSync } = await import('../lib/commands/sync.mjs')
+    await runSync(opts)
+  })
+
+program
+  .command('add-skill')
+  .description('Create a new skill scaffold')
+  .argument('<name>', 'Skill name (lowercase, hyphens, e.g. "my-skill")')
+  .option('-d, --description <desc>', 'Skill description')
+  .action(async (name, opts) => {
+    const { runAddSkill } = await import('../lib/commands/add-skill.mjs')
+    await runAddSkill(name, opts)
+  })
+
+program
+  .command('update')
+  .description('Update templates non-destructively (preserves customizations)')
+  .option('--force', 'Overwrite customized files')
+  .action(async (opts) => {
+    const { runUpdate } = await import('../lib/commands/update.mjs')
+    await runUpdate(opts)
+  })
+
+program
+  .command('list')
+  .alias('ls')
+  .description('Show current project configuration and installed components')
+  .option('--rules', 'Show rule file summaries with titles')
+  .action(async (opts) => {
+    const { runList } = await import('../lib/commands/list.mjs')
+    await runList(opts)
+  })
+
+program
+  .command('add-platform')
+  .description('Add a new AI platform to an existing project')
+  .argument('<platform>', 'Platform ID (claude, cursor, codex, gemini, antigravity, windsurf)')
+  .action(async (platform) => {
+    const { runAddPlatform } = await import('../lib/commands/add-platform.mjs')
+    await runAddPlatform(platform)
+  })
+
+program
+  .command('add-skill-pack')
+  .description('Add a skill pack to an existing project')
+  .argument('<pack>', 'Skill pack ID (e.g. frontend-design, security-best-practices)')
+  .action(async (pack) => {
+    const { runAddSkillPack } = await import('../lib/commands/add-skill-pack.mjs')
+    await runAddSkillPack(pack)
+  })
+
+program
+  .command('doctor')
+  .description('Check project configuration for issues')
+  .option('--deep', 'Run additional deep checks (placeholders, sync status, rule completeness)')
+  .action(async (opts) => {
+    const { runDoctor } = await import('../lib/commands/doctor.mjs')
+    await runDoctor(opts)
+  })
+
+program
+  .command('install')
+  .alias('i')
+  .description('Install a package (rules, skills, skill-packs) from local path or npm')
+  .argument('<source>', 'Local path or npm package name (e.g. ./my-rules, @ai-rules/next)')
+  .option('--force', 'Overwrite existing files')
+  .action(async (source, opts) => {
+    const { runInstall } = await import('../lib/commands/install.mjs')
+    await runInstall(source, opts)
+  })
+
+program
+  .command('remove')
+  .alias('rm')
+  .description('Remove an installed package')
+  .argument('<name>', 'Package name to remove')
+  .action(async (name, opts) => {
+    const { runRemove } = await import('../lib/commands/remove.mjs')
+    await runRemove(name, opts)
+  })
+
+program
+  .command('diff')
+  .description('Compare local .ai/rules/ against template versions')
+  .action(async () => {
+    const { runDiff } = await import('../lib/commands/diff.mjs')
+    await runDiff()
+  })
+
+program.parse()

package/lib/adapters/antigravity.mjs

@@ -0,0 +1,70 @@
+import { join } from 'path'
+import { MARKERS } from '../utils.mjs'
+
+export const id = 'antigravity'
+export const name = 'Antigravity'
+
+export function getOutputPaths(projectRoot) {
+  return {
+    rootDoc: join(projectRoot, '.agent', 'rules.md'),
+    skillsDir: join(projectRoot, '.agent', 'skills'),
+    commandsDir: join(projectRoot, '.agent', 'workflows'),
+  }
+}
+
+export function generateRootDoc(vars) {
+  return `# Agent Rules
+
+> Project instructions for Antigravity and compatible AI agents.
+
+**${vars.projectName}** — ${vars.projectDescription || 'A software project.'}
+
+## Project Rules
+
+Read all files in \`.ai/rules/\` for complete project rules (tech stack, architecture, coding conventions, TypeScript, React, styling, naming, git workflow, testing, forbidden patterns, AI agent instructions).
+
+## Architecture Decisions & Memory
+
+- \`.ai/decisions/\` — ADRs with context and rationale
+- \`.ai/changelog/\` — Monthly change logs
+- \`.ai/skills/\` — Portable skill definitions — read and execute \`.ai/skills/<name>/skill.md\` when triggered
+- \`.ai/memory/\` — Shared memory files
+- \`.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) {
+  return `# ${manifest.name}
+
+${manifest.description}
+
+## Workflow
+
+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) provides context.
+`
+}
+
+export function generateRules() {
+  return null // Rules are in .agent/rules.md
+}
+
+export const marker = MARKERS.md

package/lib/adapters/claude.mjs

@@ -0,0 +1,85 @@
+import { join } from 'path'
+import { MARKERS } from '../utils.mjs'
+
+export const id = 'claude'
+export const name = 'Claude Code'
+
+export function getOutputPaths(projectRoot) {
+  return {
+    rootDoc: join(projectRoot, 'CLAUDE.md'),
+    skillsDir: join(projectRoot, '.claude', 'skills'),
+    commandsDir: join(projectRoot, '.claude', 'commands'),
+  }
+}
+
+export function generateRootDoc(vars) {
+  return `# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+**${vars.projectName}** — ${vars.projectDescription || 'A software project.'}
+
+## Project Rules
+
+@.ai/rules/*.md
+
+## Architecture Decisions & Memory
+
+- \`.ai/decisions/\` — ADRs with full context and rationale (@.ai/decisions/README.md)
+- \`.ai/changelog/\` — Monthly change logs with context, reasoning, and impact
+- \`.ai/skills/\` — Portable skill definitions; run \`npx agentkit sync\` to generate platform adapters
+- \`.ai/memory/\` — Shared memory files (debugging patterns, known issues, refactoring log)
+- \`.specs/\` — Epics, stories, tasks, and completed archive (@.specs/README.md)
+
+### Memory Commands
+
+| Command | Purpose |
+|---------|---------|
+| \`/adr\` | Record an architecture decision |
+| \`/devlog\` | Append a changelog entry |
+| \`/wrap-up\` | End-of-task: update all memory files at once |
+`
+}
+
+export function generateSkillStub(manifest, vars = {}) {
+  const lines = [
+    '---',
+    `name: ${manifest.name}`,
+    `description: ${manifest.description}`,
+    `user-invocable: ${manifest['user-invocable'] ?? true}`,
+  ]
+
+  if (manifest['argument-hint']) {
+    lines.push('metadata:')
+    lines.push(`  author: ${vars.projectName || 'agentkit'}`)
+    lines.push('  version: "1.0.0"')
+    lines.push(`  argument-hint: "${manifest['argument-hint']}"`)
+  }
+
+  lines.push('---', '', `# ${manifest.name}`, '')
+  lines.push(`Read and follow the skill definition at \`.ai/skills/${manifest.name}/skill.md\` exactly.`)
+  lines.push('')
+  lines.push("The user's argument (if any) provides context for this skill invocation.")
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+export function generateCommand(manifest) {
+  return `---
+name: ${manifest.name}
+description: '${manifest.description}'
+user-invocable: ${manifest['user-invocable'] ?? true}
+---
+
+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.
+`
+}
+
+export function generateRules() {
+  return null // Claude uses @file references in CLAUDE.md, no separate rules file needed
+}
+
+export const marker = MARKERS.md

package/lib/adapters/codex.mjs

@@ -0,0 +1,60 @@
+import { join } from 'path'
+import { MARKERS } from '../utils.mjs'
+
+export const id = 'codex'
+export const name = 'Codex'
+
+export function getOutputPaths(projectRoot) {
+  return {
+    rootDoc: join(projectRoot, 'AGENTS.md'),
+    skillsDir: join(projectRoot, '.codex', 'skills'),
+  }
+}
+
+export function generateRootDoc(vars) {
+  return `# AGENTS.md
+
+> Instructions for OpenAI Codex and other AI coding agents working on this repository.
+
+**${vars.projectName}** — ${vars.projectDescription || 'A software project.'}
+
+## Project Rules
+
+All project rules are maintained in \`.ai/rules/\`. Read all files in that directory before making changes (tech stack, architecture, coding conventions, TypeScript, React, styling, naming, git workflow, testing, forbidden patterns, AI agent instructions).
+
+## 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() {
+  return null // Codex doesn't support commands
+}
+
+export function generateRules() {
+  return null // Codex uses AGENTS.md directly
+}
+
+export const marker = MARKERS.md

package/lib/adapters/cursor.mjs

@@ -0,0 +1,58 @@
+import { join } from 'path'
+import { readFileSync, existsSync } from 'fs'
+import { MARKERS } from '../utils.mjs'
+
+export const id = 'cursor'
+export const name = 'Cursor'
+
+export function getOutputPaths(projectRoot) {
+  return {
+    rootDoc: join(projectRoot, '.cursor', 'rules', 'project.mdc'),
+    commandsDir: join(projectRoot, '.cursor', 'commands'),
+  }
+}
+
+export function generateRootDoc(vars) {
+  return `---
+description: Core project rules for ${vars.projectName}
+alwaysApply: true
+---
+
+# ${vars.projectName}
+
+${vars.projectDescription || 'A software project.'}
+
+## Full Documentation
+
+Read all files in \`.ai/rules/\` for complete project rules (tech stack, architecture, coding conventions, TypeScript, React, styling, naming, git workflow, testing, forbidden patterns, AI agent instructions).
+
+## Architecture Decisions & Memory
+
+- \`.ai/decisions/\` — ADRs with context and rationale
+- \`.ai/changelog/\` — Monthly change logs
+- \`.ai/skills/\` — Portable skill definitions (adr, devlog, wrap-up)
+- \`.ai/memory/\` — Shared memory files (debugging, known issues, refactoring)
+- \`.specs/\` — Epics, stories, tasks, completed archive
+`
+}
+
+export function generateSkillStub() {
+  return null // Cursor doesn't support skills directory
+}
+
+export function generateCommand(manifest) {
+  return `---
+description: '${manifest.description}'
+---
+
+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: $ARGUMENTS
+`
+}
+
+export function generateRules() {
+  return null // Cursor uses .mdc frontmatter, rules in project.mdc
+}
+
+export const marker = MARKERS.mdc