mvagnon-agents 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+```
+                                    __                 _
+ _ ____ ____ _ __ _ _ _  ___ _ _   / /_ _ __ _ ___ _ _| |_ ___
+| '  \ V / _` / _` | ' \/ _ \ ' \ / / _` / _` / -_) ' \  _(_-<
+|_|_|_\_/\__,_\__, |_||_\___/_||_/_/\__,_\__, \___|_||_\__/__/
+              |___/                      |___/
+```
+
+# AI Workflow
+
+Shared configuration and conventions to bootstrap AI coding assistants on TypeScript/React projects. One repo, one command — every tool gets the same rules, skills, and MCP servers.
+
+## Supported Tools
+
+| Tool        | Rules              | Skills / Agents                          | Root File   | MCP Config           |
+| ----------- | ------------------ | ---------------------------------------- | ----------- | -------------------- |
+| Claude Code | `.claude/rules/`   | `.claude/skills/`, `.claude/agents/`     | `CLAUDE.md` | `.mcp.json`          |
+| OpenCode    | `.opencode/rules/` | `.opencode/skills/`, `.opencode/agents/` | `AGENTS.md` | `opencode.json`      |
+| Cursor      | `.cursor/rules/`   | `.cursor/skills/`, `.cursor/agents/`     | —           | `.cursor/mcp.json`   |
+| Codex       | —                  | `.agents/skills/`                        | `AGENTS.md` | `.codex/config.toml` |
+
+## Tech Stack Coverage
+
+| Category | Technologies                                              |
+| -------- | --------------------------------------------------------- |
+| Frontend | React, Next.js, Vite, TypeScript, Tailwind CSS, ShadCN UI |
+| Backend  | Node.js, Fastify, Express, NestJS, Supabase               |
+| State    | Zustand, TanStack Query, React Context                    |
+| Testing  | Vitest, Jest, React Testing Library                       |
+| Tooling  | ESLint, Prettier, pnpm, Docker                            |
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 18
+- pnpm or npm
+
+### Installation
+
+```bash
+pnpm install
+```
+
+### Usage
+
+```bash
+# Run the bootstrap script with target path
+pnpm run bootstrap ../my-project
+
+# Or directly with node
+node bootstrap.mjs ~/projects/my-app
+```
+
+### Interactive Walkthrough
+
+The script prompts you to:
+
+1. **Select technologies** — filter rules by stack (React, TypeScript)
+2. **Select architecture** — optional (e.g. Hexagonal)
+3. **Choose mode** — symlinks (recommended) or copy files
+4. **Select target tools** — one or more (Claude Code, OpenCode, Cursor, Codex)
+
+```
+AI Workflow → /Users/you/projects/my-app
+
+◆ Select technologies
+│ [ ] React - Components, hooks, patterns
+│ [x] TypeScript - Conventions, testing
+
+◆ Select custom architecture
+│ ● None
+
+◆ Use symlinks? Yes
+
+◆ Select target tools
+│ [x] Claude Code
+│ [x] Cursor
+│ [ ] OpenCode
+│ [ ] Codex
+
+◇ Claude Code Setup
+│ Rules:      2 linked
+│ Skills:     1 linked
+│ Agents:     0 linked
+│ CLAUDE.md:  linked
+│ .mcp.json:  copied
+│ .gitignore: entries added
+
+◇ Cursor Setup
+│ Rules:      2 linked
+│ .cursor/mcp.json: copied
+│ .gitignore: entries added
+
+Done
+```
+
+## Project Structure
+
+```
+config/
+├── rules/
+│   ├── project.md                        # Generic project rules (always included)
+│   └── react-hexagonal-architecture.md   # Hexagonal architecture for React
+├── skills/
+│   └── readme-writing/                   # README generation skill
+├── agents/                               # Custom agents (optional)
+├── AGENTS.md                             # Master rules for all agents
+├── claudecode.settings.json              # Claude Code MCP config
+├── opencode.settings.json                # OpenCode MCP config
+├── cursor.mcp.json                       # Cursor MCP config
+└── codex.config.toml                     # Codex MCP config (TOML)
+
+bootstrap.mjs                             # Interactive setup script
+```
+
+## Rule Filtering
+
+Items without a technology or architecture prefix are considered generic and always included.
+
+| Selection    | Rules Included                         |
+| ------------ | -------------------------------------- |
+| None         | Generic rules only (`project.md`)      |
+| React        | Generic + `react-*.md`                 |
+| TypeScript   | Generic + `ts-*.md`                    |
+| Hexagonal    | Generic + items containing `hexagonal` |
+| React + Both | Generic + `react-*.md` + `ts-*.md`     |
+
+## Symlinks vs Copy
+
+| Mode     | Pros                                | Cons                          |
+| -------- | ----------------------------------- | ----------------------------- |
+| Symlinks | Centralized updates, no duplication | Requires source repo presence |
+| Copy     | Self-contained, portable            | Manual updates needed         |
+
+Items listed in `COPIED_RULES`, `COPIED_SKILLS`, or `COPIED_AGENTS` are always copied (never symlinked) to allow per-project customization.
+
+## Manual Installation
+
+If you prefer not to use the bootstrap script:
+
+1. Copy the `config/` folder contents to your project
+2. Rename files according to your target tool (see Supported Tools table)
+3. Update `.gitignore` as needed

package/bootstrap.mjs

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+
+import * as p from "@clack/prompts";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+// Technologies filter items by prefix (e.g., "react-*" matches "react-components")
+const TECHNOLOGIES = [
+  { value: "react", label: "React", hint: "Components, hooks, patterns" },
+  { value: "ts", label: "TypeScript", hint: "Conventions, testing" },
+];
+
+// Architectures filter items by substring match
+const ARCHITECTURES = [
+  { value: "none", label: "None", hint: "No custom architecture" },
+  { value: "hexagonal", label: "Hexagonal", hint: "Ports & adapters pattern" },
+];
+
+// Items always copied (never symlinked) to allow per-project customization
+const COPIED_RULES = ["project"];
+const COPIED_SKILLS = [];
+const COPIED_AGENTS = [];
+
+// Intermediate directory in the target project for per-project customizable resources
+const INTERMEDIATE_DIR = ".mvagnon/agents";
+
+// Tool definitions: directory structure, root files, config files, gitignore
+const TOOLS = {
+  claudecode: {
+    value: "claudecode",
+    label: "Claude Code",
+    hint: "Anthropic's CLI for Claude",
+    paths: {
+      rules: ".claude/rules",
+      skills: ".claude/skills",
+      agents: ".claude/agents",
+    },
+    rootFiles: { "AGENTS.md": "CLAUDE.md" },
+    configFiles: { "claudecode.settings.json": ".mcp.json" },
+    gitignoreEntries: [".claude", "CLAUDE.md", ".mcp.json"],
+  },
+
+  opencode: {
+    value: "opencode",
+    label: "OpenCode",
+    hint: "Open-source AI coding assistant",
+    paths: {
+      rules: ".opencode/rules",
+      skills: ".opencode/skills",
+      agents: ".opencode/agents",
+    },
+    rootFiles: { "AGENTS.md": "AGENTS.md" },
+    configFiles: { "opencode.settings.json": "opencode.json" },
+    gitignoreEntries: [".opencode", "AGENTS.md", "opencode.json"],
+  },
+
+  cursor: {
+    value: "cursor",
+    label: "Cursor",
+    hint: "AI-powered code editor",
+    paths: {
+      rules: ".cursor/rules",
+      skills: ".cursor/skills",
+      agents: ".cursor/agents",
+    },
+    rootFiles: {},
+    configFiles: { "cursor.mcp.json": ".cursor/mcp.json" },
+    gitignoreEntries: [".cursor"],
+  },
+
+  codex: {
+    value: "codex",
+    label: "Codex",
+    hint: "OpenAI's coding agent CLI",
+    paths: {
+      skills: ".agents/skills",
+    },
+    rootFiles: { "AGENTS.md": "AGENTS.md" },
+    configFiles: { "codex.config.toml": ".codex/config.toml" },
+    gitignoreEntries: [".codex", ".agents", "AGENTS.md"],
+  },
+};
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+async function main() {
+  const targetArg = process.argv[2];
+
+  if (!targetArg) {
+    console.error("Usage: ./bootstrap.sh <target-path>");
+    console.error("Example: ./bootstrap.sh ../my-project");
+    process.exit(1);
+  }
+
+  const targetPath = resolvePath(targetArg);
+
+  if (!fs.existsSync(targetPath)) {
+    console.error(`Error: Directory not found: ${targetPath}`);
+    process.exit(1);
+  }
+
+  if (!fs.statSync(targetPath).isDirectory()) {
+    console.error(`Error: Path must be a directory: ${targetPath}`);
+    process.exit(1);
+  }
+
+  console.clear();
+
+  const banner = [
+    "                                    __                 _      ",
+    " _ ____ ____ _ __ _ _ _  ___ _ _   / /_ _ __ _ ___ _ _| |_ ___",
+    "| '  \\ V / _` / _` | ' \\/ _ \\ ' \\ / / _` / _` / -_) ' \\  _(_-<",
+    "|_|_|_\\_/\\__,_\\__, |_||_\\___/_||_/_/\\__,_\\__, \\___|_||_\\__/__/",
+    "              |___/                      |___/                 ",
+  ];
+  console.log("\x1b[36m" + banner.join("\n") + "\x1b[0m\n");
+
+  p.intro(`AI Workflow → ${targetPath}`);
+
+  const config = await p.group(
+    {
+      techs: () =>
+        p.multiselect({
+          message: "Select technologies",
+          options: TECHNOLOGIES,
+          required: false,
+        }),
+
+      archs: () =>
+        p.select({
+          message: "Select custom architecture",
+          options: ARCHITECTURES,
+          required: false,
+        }),
+
+      useSymlinks: () =>
+        p.confirm({
+          message:
+            "Use symlinks? (yes: `.gitignore` updated, no: config versioned)",
+          initialValue: true,
+        }),
+
+      tools: () =>
+        p.multiselect({
+          message: "Select target tools",
+          options: Object.values(TOOLS).map((t) => ({
+            value: t.value,
+            label: t.label,
+            hint: t.hint,
+          })),
+          required: true,
+        }),
+    },
+    {
+      onCancel: () => {
+        p.cancel("Setup cancelled");
+        process.exit(0);
+      },
+    },
+  );
+
+  const selectedTechs = config.techs || [];
+  const selectedArchs = config.archs ? [config.archs] : [];
+  const useSymlinks = config.useSymlinks;
+  const selectedTools = config.tools.map((key) => TOOLS[key]);
+  const s = p.spinner();
+  const safeCopy = (src, tgt) =>
+    copyWithConfirm(src, tgt, { spinner: s, projectRoot: targetPath });
+  const linkOrCopy = useSymlinks
+    ? async (src, tgt) => createSymlink(src, tgt)
+    : safeCopy;
+
+  s.start(useSymlinks ? "Creating symlinks" : "Copying files");
+
+  const mode = useSymlinks ? "linked" : "copied";
+  const summaryLines = [];
+  const processedIntermediateFiles = new Set();
+
+  for (const tool of selectedTools) {
+    const stats = { rules: 0, skills: 0, agents: 0 };
+    const { paths } = tool;
+
+    for (const dir of Object.values(paths)) {
+      fs.mkdirSync(path.join(targetPath, dir), { recursive: true });
+    }
+
+    if (paths.rules) {
+      stats.rules = await linkMatchingItems(
+        path.join(__dirname, "config", "rules"),
+        path.join(targetPath, paths.rules),
+        selectedTechs,
+        selectedArchs,
+        linkOrCopy,
+        {
+          filterExtension: ".md",
+          copiedItems: COPIED_RULES,
+          intermediateDir: path.join(targetPath, INTERMEDIATE_DIR, "rules"),
+          processedIntermediateFiles,
+          safeCopy,
+        },
+      );
+    }
+
+    if (paths.skills) {
+      stats.skills = await linkMatchingItems(
+        path.join(__dirname, "config", "skills"),
+        path.join(targetPath, paths.skills),
+        selectedTechs,
+        selectedArchs,
+        linkOrCopy,
+        {
+          directoriesOnly: true,
+          copiedItems: COPIED_SKILLS,
+          intermediateDir: path.join(targetPath, INTERMEDIATE_DIR, "skills"),
+          processedIntermediateFiles,
+          safeCopy,
+        },
+      );
+    }
+
+    if (paths.agents) {
+      stats.agents = await linkMatchingItems(
+        path.join(__dirname, "config", "agents"),
+        path.join(targetPath, paths.agents),
+        selectedTechs,
+        selectedArchs,
+        linkOrCopy,
+        {
+          directoriesOnly: true,
+          copiedItems: COPIED_AGENTS,
+          intermediateDir: path.join(targetPath, INTERMEDIATE_DIR, "agents"),
+          processedIntermediateFiles,
+          safeCopy,
+        },
+      );
+    }
+
+    for (const [src, dest] of Object.entries(tool.rootFiles)) {
+      const srcPath = path.join(__dirname, "config", src);
+      if (fs.existsSync(srcPath)) {
+        await linkOrCopy(srcPath, path.join(targetPath, dest));
+      }
+    }
+
+    for (const [src, dest] of Object.entries(tool.configFiles)) {
+      const srcPath = path.join(__dirname, "config", src);
+      if (fs.existsSync(srcPath)) {
+        const destPath = path.join(targetPath, dest);
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        await safeCopy(srcPath, destPath);
+      }
+    }
+
+    if (useSymlinks) {
+      updateGitignore(targetPath, tool);
+      addGitignoreEntry(targetPath, INTERMEDIATE_DIR, "mvagnon/agents");
+    }
+
+    const toolSummary = [
+      `Rules:  ${stats.rules} ${mode}`,
+      paths.skills ? `Skills: ${stats.skills} ${mode}` : null,
+      paths.agents ? `Agents: ${stats.agents} ${mode}` : null,
+      ...Object.values(tool.rootFiles).map((f) => `${f}: ${mode}`),
+      ...Object.values(tool.configFiles).map((f) => `${f}: copied`),
+      useSymlinks ? `.gitignore: entries added` : `.gitignore: not modified`,
+    ].filter(Boolean);
+
+    summaryLines.push({ tool, lines: toolSummary });
+  }
+
+  s.stop("Setup complete");
+
+  for (const { tool, lines } of summaryLines) {
+    p.note(lines.join("\n"), `${tool.label} Setup`);
+  }
+
+  p.note(
+    [
+      "1. Modify `project.md` to add project-specific rules;",
+      "2. Add rules, skills, agents, MCPs or plugins based on your needs for each tool.",
+    ].join("\n"),
+    "Next Steps",
+  );
+
+  p.outro("Done");
+}
+
+function resolvePath(inputPath) {
+  if (inputPath.startsWith("~")) {
+    inputPath = inputPath.replace("~", process.env.HOME);
+  }
+  return path.resolve(inputPath);
+}
+
+function isTechOrArchSpecific(name) {
+  const allTechs = TECHNOLOGIES.map((t) => t.value);
+  const allArchs = ARCHITECTURES.filter((a) => a.value !== "none").map(
+    (a) => a.value,
+  );
+
+  return (
+    allTechs.some((tech) => name.startsWith(`${tech}-`)) ||
+    allArchs.some((arch) => name.includes(arch))
+  );
+}
+
+function shouldInclude(name, selectedTechs, selectedArchs) {
+  if (!isTechOrArchSpecific(name)) return true;
+
+  const matchesTech = selectedTechs.some((tech) => name.startsWith(`${tech}-`));
+  const matchesArch = selectedArchs
+    .filter((arch) => arch !== "none")
+    .some((arch) => name.includes(arch));
+
+  return matchesTech || matchesArch;
+}
+
+async function linkMatchingItems(
+  sourceDir,
+  targetDir,
+  selectedTechs,
+  selectedArchs,
+  linkOrCopy,
+  {
+    filterExtension,
+    directoriesOnly,
+    copiedItems = [],
+    intermediateDir,
+    safeCopy,
+    processedIntermediateFiles = new Set(),
+  } = {},
+) {
+  if (!fs.existsSync(sourceDir)) return 0;
+
+  let count = 0;
+
+  for (const entry of fs.readdirSync(sourceDir)) {
+    const fullPath = path.join(sourceDir, entry);
+    const isDir = fs.statSync(fullPath).isDirectory();
+
+    if (directoriesOnly && !isDir) continue;
+    if (filterExtension && !entry.endsWith(filterExtension)) continue;
+
+    const name = entry.replace(/\.md$/, "");
+
+    if (!shouldInclude(name, selectedTechs, selectedArchs)) continue;
+
+    const isCopied = copiedItems.includes(name) && intermediateDir;
+
+    if (isCopied) {
+      const intermediatePath = path.join(intermediateDir, entry);
+      fs.mkdirSync(intermediateDir, { recursive: true });
+
+      if (!processedIntermediateFiles.has(intermediatePath)) {
+        await safeCopy(fullPath, intermediatePath);
+        processedIntermediateFiles.add(intermediatePath);
+      }
+
+      await linkOrCopy(intermediatePath, path.join(targetDir, entry));
+    } else {
+      await linkOrCopy(fullPath, path.join(targetDir, entry));
+    }
+
+    count++;
+  }
+
+  return count;
+}
+
+async function copyWithConfirm(source, target, { spinner, projectRoot } = {}) {
+  if (fs.existsSync(target)) {
+    try {
+      if (!fs.lstatSync(target).isSymbolicLink()) {
+        const label = projectRoot
+          ? path.relative(projectRoot, target)
+          : path.basename(target);
+        if (spinner) spinner.stop("Existing file found");
+        const overwrite = await p.confirm({
+          message: `${label} already exists. Overwrite?`,
+          initialValue: false,
+        });
+        if (p.isCancel(overwrite)) {
+          p.cancel("Setup cancelled");
+          process.exit(0);
+        }
+        if (spinner) spinner.start("Continuing setup");
+        if (!overwrite) return false;
+      }
+    } catch {
+      // lstat failed, proceed with copy
+    }
+  }
+
+  copyPath(source, target);
+  return true;
+}
+
+function removePath(target) {
+  if (
+    fs.existsSync(target) ||
+    fs.lstatSync(target, { throwIfNoEntry: false })
+  ) {
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+}
+
+function createSymlink(source, target) {
+  removePath(target);
+  fs.symlinkSync(source, target);
+}
+
+function copyPath(source, target) {
+  removePath(target);
+
+  if (fs.statSync(source).isDirectory()) {
+    fs.cpSync(source, target, { recursive: true });
+  } else {
+    fs.copyFileSync(source, target);
+  }
+}
+
+function updateGitignore(targetPath, tool) {
+  const gitignorePath = path.join(targetPath, ".gitignore");
+  const sectionHeader = `# ${tool.label} Configuration`;
+  let content = "";
+
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, "utf-8");
+
+    if (content.includes(sectionHeader)) return;
+
+    if (content.length > 0 && !content.endsWith("\n")) content += "\n";
+    content += "\n";
+  }
+
+  content += sectionHeader + "\n";
+  content += tool.gitignoreEntries.join("\n") + "\n";
+
+  fs.writeFileSync(gitignorePath, content);
+}
+
+function addGitignoreEntry(targetPath, entry, sectionComment) {
+  const gitignorePath = path.join(targetPath, ".gitignore");
+  let content = "";
+
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, "utf-8");
+    if (content.split("\n").some((line) => line.trim() === entry)) return;
+    if (content.length > 0 && !content.endsWith("\n")) content += "\n";
+    content += "\n";
+  }
+
+  if (sectionComment) {
+    content += `# ${sectionComment}\n`;
+  }
+  content += entry + "\n";
+  fs.writeFileSync(gitignorePath, content);
+}
+
+main().catch(console.error);

package/config/AGENTS.md

@@ -0,0 +1,77 @@
+# Master Rules
+
+## Project-Specific Rules
+
+Find the project-specific master rules here → `project.md`.
+
+## Before Writing Code
+
+Before writing or modifying code that uses any external library:
+
+1. **First**, resolve the library with _Context7 MCP_ to get the up-to-date documentation;
+2. **Only** if Context7 returns no results or insufficient info, fall back to _Exa MCP_ as a secondary source.
+
+> **Important:** ALWAYS prefer Context7 documentation over training data as the source of truth, especially for critical features (security, billing, authentication, payments, etc.).
+
+## While Writing Code
+
+### Code Conventions
+
+- ALWAYS group all imports in a single block at the top of the file, with no blank lines between them;
+- ALWAYS organize the code into blocs with each bloc representing a distinct logic. Each bloc is separated with a line jump (example below).
+
+> **Example (React):**
+>
+> ```tsx
+> export function UserProfile({ userId }: UserProfileProps) {
+>   const { data: user, isLoading } = useUser(userId);
+>   const { mutate: updateUser } = useUpdateUser();
+>
+>   const displayName = user?.name ?? "Anonymous";
+>   const initials = displayName.slice(0, 2).toUpperCase();
+>
+>   const handleSave = (values: UserFormValues) => {
+>     updateUser({ id: userId, ...values });
+>   };
+>
+>   if (isLoading) return <Skeleton />;
+>
+>   return (
+>     <Card>
+>       <Avatar initials={initials} />
+>       <UserForm defaultValues={user} onSubmit={handleSave} />
+>     </Card>
+>   );
+> }
+> ```
+>
+> **Example (FastAPI):**
+>
+> ```python
+> @router.get("/users/{user_id}")
+> async def get_user(user_id: UUID, db: Session = Depends(get_db)) -> UserResponse:
+>     """Retrieve a user by ID."""
+>     user = await db.get(User, user_id)
+>
+>     if not user:
+>         raise HTTPException(status_code=404, detail="User not found")
+>
+>     return UserResponse.model_validate(user)
+> ```
+
+### Documentation & Logging
+
+- Write TSDoc/docstrings ONLY for **exported** functions, classes, types, and interfaces;
+- NEVER add comments on trivial logic (hook, constant declaration, etc.);
+- NEVER add logs unless requested;
+- ALWAYS comment complex logic (RegEx, etc.);
+- Generic code (style variables, UI components, etc.) should ALWAYS be reusable.
+
+## After Writing Code
+
+CRITICAL: ALWAYS check the following after modifying the codebase. Iterate until complete:
+
+- [ ] KISS (Keep It Stupid Simple) principle is applied
+- [ ] DRY (Don't Repeat Yourself) principle is applied
+- [ ] No logs were added without prior consent
+- [ ] Code is properly spaced into logical blocks

package/config/claudecode.settings.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "exa": {
+      "type": "http",
+      "url": "https://mcp.exa.ai/mcp"
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "ctx7sk-09be8e62-174a-424a-81ef-166f2b2c94a2"
+      }
+    }
+  }
+}

package/config/codex.config.toml

@@ -0,0 +1,10 @@
+[mcp_servers.exa]
+url = "https://mcp.exa.ai/mcp"
+enabled = true
+
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"
+enabled = true
+
+[mcp_servers.context7.http_headers]
+CONTEXT7_API_KEY = "ctx7sk-09be8e62-174a-424a-81ef-166f2b2c94a2"

package/config/cursor.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "exa": {
+      "url": "https://mcp.exa.ai/mcp"
+    },
+    "context7": {
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "ctx7sk-09be8e62-174a-424a-81ef-166f2b2c94a2"
+      }
+    }
+  }
+}

package/config/opencode.settings.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".opencode/rules/*.md"],
+  "mcp": {
+    "exa": {
+      "enabled": true,
+      "type": "remote",
+      "url": "https://mcp.exa.ai/mcp",
+      "headers": {}
+    },
+    "context7": {
+      "enabled": true,
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "ctx7sk-09be8e62-174a-424a-81ef-166f2b2c94a2"
+      }
+    }
+  }
+}

package/config/rules/project.md

@@ -0,0 +1,7 @@
+# Project-Specific Master Rules
+
+- Write;
+- Down;
+- Project;
+- Specific;
+- Rules.

package/config/rules/react-hexagonal-architecture.md

@@ -0,0 +1,50 @@
+# React Hexagonal Architecture
+
+## Structure
+
+```
+src/
+├── application/       # UI — Can freely use React
+│   ├── components/    # React components
+│   ├── hooks/         # Business hooks (consume domain)
+│   ├── pages/         # Route components
+│   └── providers/     # Context providers
+├── domain/            # Business — Pure TypeScript, ZERO React dependencies
+│   ├── entities/      # Business models
+│   ├── ports/         # Interfaces/contracts
+│   └── lib/           # Pure functions
+└── infrastructure/    # External — Implements ports
+    ├── api/           # HTTP/GraphQL clients
+    └── config/        # Configuration, feature flags
+```
+
+## Layer Rules
+
+### Domain (core)
+
+- **No** React dependencies (no JSX, no hooks)
+- Pure functions, testable in isolation
+- Defines `ports` (interfaces) that infrastructure implements
+
+### Application (UI)
+
+- Consumes domain via custom hooks
+- Components split by responsibility
+- State management: `useState` → `useReducer` → Context → Zustand (progressive escalation)
+
+### Infrastructure (adapters)
+
+- Implements ports defined by domain
+- Handles side effects (API, storage, analytics)
+- Transforms external responses into domain entities
+
+## Dependency Principle
+
+```
+Application → Domain ← Infrastructure
+              ↑
+         (ports/interfaces)
+```
+
+- Application and Infrastructure depend on Domain
+- Domain depends on nothing external

package/config/skills/readme-writing/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: readme-writing
+description: Write README.md for a project.
+---
+
+# README Generator Skill
+
+Generates or updates the `README.md` file at the project root.
+
+## Workflow
+
+1. **Analyze the project**
+   - Read `package.json` (or equivalent) for metadata;
+   - Read `.claude/CLAUDE.md` and `.claude/rules/` to understand context;
+   - Scan folder structure (`src/`, `lib/`, `app/`, etc.);
+   - Identify the tech stack in use.
+
+2. **Collect existing information**
+   - If `README.md` exists: read it to preserve custom content;
+   - Identify sections to keep vs regenerate.
+
+3. **Generate content**
+   - Follow the structure below;
+   - Use a professional and concise tone;
+   - No emojis unless explicitly requested.
+
+## README Structure
+
+```markdown
+# Project Name
+
+Short and impactful description (1-2 sentences).
+
+## Features
+
+- Feature 1;
+- Feature 2.
+
+## Tech Stack
+
+| Category | Technologies |
+| -------- | ------------ |
+| Frontend | ...          |
+| Backend  | ...          |
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= X.X;
+- pnpm/npm.
+
+### Environment Files
+
+#### `.env`
+
+\`\`\`text
+ENV_VAR=
+\`\`\`
+
+#### `.env.local`
+
+\`\`\`text
+ENV_LOCAL_VAR=
+\`\`\`
+
+### Installation
+
+\`\`\`bash
+pnpm install
+\`\`\`
+
+### Development
+
+\`\`\`bash
+pnpm dev
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+src/
+├── ...
+\`\`\`
+
+## Scripts
+
+| Script | Description |
+| ------ | ----------- |
+| `dev`  | ...         |
+
+## Rules
+
+- **Never invent** features not present in the code;
+- **Preserve** existing custom sections (Contributing, Acknowledgments, etc.);
+- **Adapt** the structure based on project type (lib, app, monorepo);
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "mvagnon-agents",
+  "version": "1.0.0",
+  "description": "Shared configuration and conventions to bootstrap AI coding assistants.",
+  "type": "module",
+  "bin": {
+    "opencode-workflow": "./bootstrap.mjs"
+  },
+  "files": [
+    "bootstrap.mjs",
+    "config/"
+  ],
+  "scripts": {
+    "bootstrap": "node bootstrap.mjs"
+  },
+  "keywords": [
+    "ai",
+    "coding-assistant",
+    "claude-code",
+    "cursor",
+    "opencode",
+    "codex",
+    "bootstrap",
+    "typescript",
+    "react"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  }
+}