@clubmatto/ai-kit 0.0.1

package/scripts/fetch-playwright-skills.ts

@@ -0,0 +1,79 @@
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const rootDir = join(__dirname, "..");
+const skillsDir = join(rootDir, "src", "skills", "playwright-cli");
+
+const GITHUB_API = "https://api.github.com";
+const REPO = "microsoft/playwright-cli";
+
+const args = process.argv.slice(2);
+const VERSION = args[0] || "v0.1.1";
+
+interface GitHubFile {
+  name: string;
+  path: string;
+  type: "file" | "dir";
+  download_url?: string;
+  url?: string;
+}
+
+async function fetchJson(url: string): Promise<GitHubFile[]> {
+  const res = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.github.v3+json",
+      "User-Agent": "ai-kit",
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+  }
+  return (await res.json()) as GitHubFile[];
+}
+
+async function fetchFile(url: string): Promise<string> {
+  const res = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.github.v3.raw",
+      "User-Agent": "ai-kit",
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+  }
+  return res.text();
+}
+
+async function main() {
+  console.log(`Fetching playwright-cli skills from ${REPO}@${VERSION}...`);
+
+  const baseUrl = `${GITHUB_API}/repos/${REPO}/contents/skills/playwright-cli?ref=${VERSION}`;
+  const files = await fetchJson(baseUrl);
+
+  mkdirSync(skillsDir, { recursive: true });
+  mkdirSync(join(skillsDir, "references"), { recursive: true });
+
+  for (const file of files) {
+    if (file.type === "dir" && file.name === "references") {
+      const refs = await fetchJson(file.url!);
+      for (const ref of refs) {
+        const content = await fetchFile(ref.download_url!);
+        const targetPath = join(skillsDir, "references", ref.name);
+        writeFileSync(targetPath, content);
+        console.log(`  - references/${ref.name}`);
+      }
+    } else if (file.type === "file") {
+      const content = await fetchFile(file.download_url!);
+      const targetPath = join(skillsDir, file.name);
+      writeFileSync(targetPath, content);
+      console.log(`  - ${file.name}`);
+    }
+  }
+
+  console.log(`\nDone! Skills written to src/skills/playwright-cli/`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/agents/monorepo.md

@@ -0,0 +1,30 @@
+# Agents.md
+
+This is a monorepo containing apps in many languages.
+
+You MUST follow the specific rules for each language. **ALWAYS** start from
+checking out README.md.
+
+## Build Systems
+
+- **Kotlin/Java**: Gradle (Kotlin DSL). Use `./gradlew` commands.
+- **Go**: Go modules. Use `go` commands.
+- **TypeScript**: Use `npm`.
+
+## How to Find the Right Rules
+
+1. **Identify the primary language** of the file(s) you're working with.
+2. **Navigate to `.agents/rules/`** and open the corresponding file:
+   - TypeScript → `typescript.md`
+   - Go → `go.md`
+   - Kotlin → `kotlin.md`
+   - etc.
+
+CRITICAL: When you encounter a file reference (e.g., `@.ai/rules/go.md`), use the Read tool to load it on a need-to-know basis.
+
+## Additional Guidelines
+
+- [Plan Mode](.agents/rules/plan-mode.md)
+- [When You're Unsure](.agents/rules/unsure.md)
+
+_{{AGENTS_FOOTER}}_

package/src/agents/opencode.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
+      },
+      "enabled": false
+    },
+    "circleci": {
+      "type": "local",
+      "command": ["npx", "-y", "@circleci/mcp-server-circleci@latest"],
+      "environment": {
+        "CIRCLECI_TOKEN": "{env:CIRCLECI_TOKEN}",
+        "CIRCLECI_BASE_URL": "https://circleci.com"
+      },
+      "enabled": false
+    },
+    "MiniMax": {
+      "type": "local",
+      "command": ["uvx", "minimax-coding-plan-mcp", "-y"],
+      "environment": {
+        "MINIMAX_API_KEY": "{env:MINIMAX_API_KEY}",
+        "MINIMAX_API_HOST": "https://api.minimax.io"
+      },
+      "enabled": false
+    }
+  }
+}

package/src/cmd/sync.ts

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import {
+  readAgents,
+  getCommandConfig,
+  readContent,
+  readConfigs,
+  SyncItem,
+} from "../reader";
+import { readManifest, writeManifest } from "../manifest";
+import { processTemplate } from "../template";
+import { log, SyncStats } from "../output";
+import { Logger } from "../logger";
+
+const rootDir = join(__dirname, "..", "..", "..");
+
+export interface SourceDirs {
+  rules: string;
+  skills: string;
+  agents: string;
+  commands: string;
+}
+
+const defaultSourceDirs: SourceDirs = {
+  rules: join(rootDir, "src", "rules"),
+  skills: join(rootDir, "src", "skills"),
+  agents: join(rootDir, "src", "agents"),
+  commands: join(rootDir, "src", "commands"),
+};
+
+interface SyncOptions {
+  skipOpencode?: boolean;
+}
+
+export async function sync(
+  cwd: string,
+  version: string,
+  options: SyncOptions,
+  logger: Logger = log,
+  sourceDirs: SourceDirs = defaultSourceDirs,
+): Promise<void> {
+  const manifest = readManifest(cwd);
+  logger.logo(version);
+
+  if (manifest && manifest.version === version) {
+    logger.success(`Already at latest version (${version})`);
+    return;
+  }
+
+  logger.welcome();
+  const counts = await doSync(cwd, version, options, logger, sourceDirs);
+  logger.summary(counts);
+}
+
+function writeItem(aiDir: string, file: SyncItem): void {
+  const targetDir = join(aiDir, file.type);
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+  const targetPath = join(targetDir, file.name);
+  const parentDir = dirname(targetPath);
+  if (!existsSync(parentDir)) {
+    mkdirSync(parentDir, { recursive: true });
+  }
+  writeFileSync(targetPath, processTemplate(file.content));
+}
+
+async function doSync(
+  cwd: string,
+  version: string,
+  options: SyncOptions,
+  logger: Logger,
+  sourceDirs: SourceDirs,
+): Promise<SyncStats> {
+  const aiDir = join(cwd, ".agents");
+
+  if (!existsSync(aiDir)) {
+    mkdirSync(aiDir, { recursive: true });
+  }
+
+  const contentFiles = readContent(sourceDirs.rules, sourceDirs.skills);
+  const rootFiles = readConfigs(sourceDirs.agents);
+  const agentsFile = readAgents(sourceDirs.agents);
+
+  const rules = contentFiles.filter((f) => f.type === "rules");
+
+  const stats: SyncStats = { rules: 0, skills: 0, commands: 0 };
+
+  const installedRootFiles: string[] = [];
+  if (!options.skipOpencode) {
+    const commandConfig = getCommandConfig(sourceDirs.commands);
+    stats.commands = Object.keys(commandConfig).length;
+
+    if (Object.keys(commandConfig).length > 0) {
+      logger.section("commands");
+      for (const name of Object.keys(commandConfig)) {
+        logger.success(`${name}.md`);
+      }
+    }
+
+    if (rootFiles.length > 0) {
+      logger.section("configs");
+      for (const file of rootFiles) {
+        let content = file.content;
+        if (
+          file.name === "opencode.json" &&
+          Object.keys(commandConfig).length > 0
+        ) {
+          const config = JSON.parse(content);
+          config.command = commandConfig;
+          content = JSON.stringify(config, null, 2) + "\n";
+        }
+        const targetPath = join(cwd, file.name);
+        writeFileSync(targetPath, content);
+        logger.success(`${file.name}`);
+        installedRootFiles.push(file.name);
+      }
+    }
+  }
+
+  if (agentsFile) {
+    const targetPath = join(cwd, agentsFile.name);
+    writeFileSync(targetPath, processTemplate(agentsFile.content));
+    logger.success(`${agentsFile.name}`);
+  }
+
+  if (rules.length > 0) {
+    logger.section("rules");
+    for (const file of rules) {
+      writeItem(aiDir, file);
+      logger.success(`${file.name}`);
+      stats.rules++;
+    }
+  }
+
+  const skills = contentFiles.filter((f) => f.type === "skills");
+
+  if (skills.length > 0) {
+    logger.section("skills");
+    const skillDirs = [...new Set(skills.map((f) => f.name.split("/")[0]))];
+    stats.skills = skillDirs.length;
+    for (const dir of skillDirs) {
+      const dirFiles = skills.filter((f) => f.name.startsWith(dir + "/"));
+      logger.success(`${dir} (${dirFiles.length} files)`);
+      for (const file of dirFiles) {
+        writeItem(aiDir, file);
+      }
+    }
+  }
+
+  writeManifest(cwd, {
+    version,
+    installedAt: new Date().toISOString(),
+    rootFiles: installedRootFiles,
+  });
+
+  return stats;
+}

package/src/commands/commit.md

@@ -0,0 +1,43 @@
+---
+description: Commit the work done in this session with a structured commit message.
+---
+
+Create a commit with the following format:
+
+## Commit Message Format
+
+**First line (one-liner):**
+
+- Use conventional commits format: `<type>: <description>`
+- Examples: `feat: add init command`, `fix: resolve path issue`, `docs: update README`
+
+**Body (bullet list):**
+
+- List the main changes made in this session
+- Each item should be a brief description of a specific change
+
+**Sign-off:**
+
+- End with: `created with the help of <MODEL>`
+- Use the current model name (e.g. "MiniMax", "GPT-4", "Claude")
+
+## Example
+
+```
+feat: add init and update commands
+
+- Created init command for first-time setup
+- Added manifest tracking in .ai/.ai-kit
+- Implemented update command for version sync
+- Added --skip-opencode option
+
+created with the help of MiniMax
+```
+
+## Process
+
+1. First, review all changes with `git status` and `git diff`
+2. Write a concise one-liner following conventional commits
+3. List the key changes as bullet points
+4. Add the sign-off line with the current model
+5. Commit with `git commit -m "your message"`

package/src/commands/interview.md

@@ -0,0 +1,92 @@
+---
+description: Interview the user to define a feature, then generate a task‑oriented implementation plan as a markdown document.
+---
+
+# Implementation Plan Generation
+
+You are a technical architect. Your task is to conduct a structured interview
+with the user, then produce a \*
+\*task‑oriented implementation plan\*\* — not a narrative PRD. The final output
+must be a series of concrete, actionable
+tasks, each with explicit sequential actions, and verification steps.
+
+Follow the process below. Skip steps only if clearly irrelevant.
+
+## Process
+
+### 1. Problem Elicitation
+
+Ask the user for a detailed description of the problem they want to solve. Probe
+for:
+
+- Current pain points or limitations
+- User impact and severity
+- Any initial solution ideas they have in mind
+
+### 2. Context Verification
+
+Explore the codebase to verify the user's assertions. Understand the current
+state of relevant modules, existing
+patterns, and potential constraints. **Do not ask the user for this
+information—investigate it yourself.**
+
+### 3. Option Exploration
+
+Ask whether the user has considered alternative approaches. Based on your
+understanding of the codebase, present 1-3
+other viable options with brief trade-offs (complexity, effort,
+maintainability).
+
+### 4. Deep Dive Interview
+
+Conduct a thorough interview about the proposed implementation. Your goal is to
+gather **everything needed to write
+concrete tasks**. Cover:
+
+- Exact files to create/modify (capture paths **relative to project root**)
+- Specific dependencies to add (with version research notes)
+- Precise code changes (what, where, why)
+- Edge cases and error states
+- Performance expectations
+- Compatibility requirements
+- Security considerations
+
+### 5. Scope Definition
+
+Explicitly define what is **in scope** and what is **out of scope** for this
+plan. Confirm with the user.
+
+### 6. Task Breakdown
+
+Decompose the implementation into **discrete, executable tasks**. Each task must
+follow this exact structure:
+
+## Tasks
+
+### N. [Task Title]
+
+**Actions:**
+
+1. [Specific, sequential action]
+2. [Next action, with code block if needed]
+3. [Etc.]
+
+**Verification:
+** [Exact command to run or observable outcome that confirms this task is complete]
+
+**Rules for tasks:**
+
+- File paths must be **relative to project root** (no absolute paths, no
+  `/Users/...`)
+- Actions must be **atomic**—one logical change per numbered step
+- Include inline code blocks where syntax matters
+- Verification must be **executable** (a command, a test, a visible UI state)
+- Tasks should be **orderable**—later tasks may depend on earlier ones
+
+### 7. Plan Generation
+
+Once all information is gathered, generate the complete implementation plan
+using the format above. The plan should be
+ready to paste directly into a markdown document.
+
+Begin the interview now.

package/src/commands/synth.md

@@ -0,0 +1,45 @@
+---
+description: To consolidate the key learnings, patterns, successful code structures, and conceptual insights from the current session into a reusable, LLM-friendly reference document.
+---
+
+Synthesize the core work, discoveries, and decisions from this development
+session into a structured, clear, and
+future-oriented document. This document should enable an LLM or a future
+developer to quickly understand and reuse the
+outcomes of this session.
+
+## 1. Core Task Summary
+
+Summarize the central problem or goal of this session in 1-2 sentences.
+
+## 2. Key Outcomes & Solutions
+
+List the main features implemented, critical bugs fixed, or core modules
+completed. For complex items, provide **code
+snippets, architectural descriptions**, or key configurations.
+
+## 3. Learnings & Discoveries
+
+Document important insights gained during this session, such as:
+
+- New usages or best practices for specific libraries, APIs, or tools.
+- New understandings about system design or data flow.
+- Pitfalls encountered and their solutions.
+
+## 4. Reusable Patterns & Code Templates
+
+Extract patterns, code templates, or configuration snippets that can be \*
+\*directly applied to future projects or similar
+tasks\*\*. Include brief context and usage instructions.
+
+## 5. LLM Collaboration Notes (Optional)
+
+If this session involved prompt techniques, instruction patterns, or context
+management methods particularly useful for
+collaborating with an LLM, document them here.
+
+## Synthesis Process
+
+1. First, review the entire session's conversation history and code changes.
+2. Then, synthesize the content strictly following the section structure above.
+3. The final output must be a complete, standalone Markdown document.

package/src/index.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { sync } from "./cmd/sync";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const version = JSON.parse(
+  readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8"),
+).version;
+
+const program = new Command();
+
+program
+  .name("@clubmatto/ai-kit")
+  .description("The AI configuration CLI from Club Matto")
+  .version(version)
+  .option("--skip-opencode", "Skip installing opencode.json to project root");
+
+program
+  .command("sync")
+  .description("Initialize or update AI configuration")
+  .action(() => sync(process.cwd(), version, program.opts()));
+
+program.parse();

package/src/logger.ts

@@ -0,0 +1,10 @@
+import { SyncStats } from "./output";
+
+export interface Logger {
+  logo: (version: string) => void;
+  welcome: () => void;
+  section: (msg: string) => void;
+  success: (msg: string) => void;
+  final: (msg: string) => void;
+  summary: (counts: SyncStats) => void;
+}

package/src/manifest.ts

@@ -0,0 +1,29 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+interface Manifest {
+  version: string;
+  installedAt: string;
+  rootFiles?: string[];
+}
+
+const AI_DIR = ".agents";
+const MANIFEST_FILE = ".ai-kit";
+
+function getManifestPath(cwd: string): string {
+  return join(cwd, AI_DIR, MANIFEST_FILE);
+}
+
+export function readManifest(cwd: string): Manifest | null {
+  const path = getManifestPath(cwd);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+export function writeManifest(cwd: string, manifest: Manifest): void {
+  const dir = join(cwd, AI_DIR);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(getManifestPath(cwd), JSON.stringify(manifest, null, 2));
+}

package/src/output.ts

@@ -0,0 +1,66 @@
+import gradient from "gradient-string";
+
+const brand = gradient(["#ff006e", "#fb5607", "#ffbe0b", "#8338ec", "#3a86ff"]);
+
+type Color = "green" | "cyan" | "yellow" | "red" | "dim" | "white" | "reset";
+
+const colors: Record<Color, string> = {
+  green: "\x1b[32m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  dim: "\x1b[90m",
+  white: "\x1b[37m",
+  reset: "\x1b[0m",
+};
+
+function colorize(text: string, color: Color): string {
+  return `${colors[color]}${text}${colors.reset}`;
+}
+
+export interface SyncStats {
+  rules: number;
+  skills: number;
+  commands: number;
+}
+
+export const log = {
+  logo: (version: string) => {
+    console.log(
+      brand(`ai-kit v${version}`) +
+        "  " +
+        colorize("The AI configuration CLI", "dim"),
+    );
+    console.log(colorize("from Club Matto\n", "dim"));
+  },
+
+  welcome: () => {
+    console.log(
+      colorize(
+        "  Syncing AI rules, skills, and commands to your project...\n",
+        "dim",
+      ),
+    );
+  },
+
+  section: (msg: string) => console.log(colorize(`  → ${msg}`, "cyan")),
+
+  success: (msg: string) => console.log(colorize(`    ✓ ${msg}`, "green")),
+
+  final: (msg: string) => console.log(colorize(`  ✓ ${msg}`, "green")),
+
+  summary: (counts: SyncStats) => {
+    console.log(colorize("\n  ✓ Done!", "green"));
+    console.log(
+      colorize(`  → `, "dim") +
+        colorize(counts.commands.toString(), "white") +
+        colorize(` commands`, "dim") +
+        colorize(`, `, "dim") +
+        colorize(counts.rules.toString(), "white") +
+        colorize(` rules`, "dim") +
+        colorize(`, `, "dim") +
+        colorize(counts.skills.toString(), "white") +
+        colorize(` skills`, "dim"),
+    );
+  },
+};