create-baton 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# create-baton
+
+Set up the [Baton](https://github.com/darwesh88/baton) AI orchestration protocol in any project with one command.
+
+## Usage
+
+```bash
+npm create baton
+```
+
+Or with npx:
+
+```bash
+npx create-baton
+```
+
+## What It Does
+
+Baton turns any AI coding assistant into a self-managing project partner. This CLI sets up:
+
+- **BATON_v3.1.md** — The core protocol
+- **skills/** — Proven patterns library (security, testing, stack guides)
+- **.ai-rules/** — Stub files for AI to fill during discovery
+- **handoff/** — Session handoff directory
+- **IDE config** — CLAUDE.md, .cursorrules, or .windsurfrules based on your tool
+
+## How It Works
+
+```
+$ npx create-baton
+
+  Baton — AI Orchestration Protocol v3.1
+
+? What AI coding tool are you using?  → Claude Code
+? What's your primary stack?          → Next.js + Supabase
+? Project name?                       → my-app
+
+  Setting up Baton...
+
+  ✓ Copied BATON_v3.1.md
+  ✓ Copied skills/ (8 core + 2 stack + 1 pattern)
+  ✓ Created .ai-rules/ (4 stub files)
+  ✓ Created handoff/
+  ✓ Created CLAUDE.md
+  ✓ Created PROGRESS.md, BACKLOG.md, FEATURES.md
+
+  Done! Next steps:
+    1. Open this folder in your AI coding tool
+    2. Tell the AI: "Read BATON_v3.1.md and begin"
+```
+
+## Requirements
+
+- Node.js 18+
+
+## License
+
+MIT

package/bin/create-baton.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 18) {
+  console.error('Baton requires Node.js 18 or higher. You are running ' + process.version);
+  process.exit(1);
+}
+
+require('../src/index.js');

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-baton",
+  "version": "1.0.0",
+  "description": "Set up Baton AI orchestration protocol in any project",
+  "bin": {
+    "create-baton": "./bin/create-baton.js"
+  },
+  "scripts": {
+    "prep": "node scripts/prep-templates.js",
+    "prepublishOnly": "node scripts/prep-templates.js"
+  },
+  "keywords": [
+    "ai",
+    "orchestration",
+    "protocol",
+    "claude",
+    "cursor",
+    "windsurf",
+    "baton",
+    "scaffolding"
+  ],
+  "author": "darwesh88",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darwesh88/baton.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/darwesh88/baton",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2"
+  }
+}

package/src/constants.js

@@ -0,0 +1,30 @@
+// IDE tool → config file mapping
+const IDE_MAP = {
+  'Claude Code': { file: 'CLAUDE.md', template: 'CLAUDE.md.template' },
+  'Cursor': { file: '.cursorrules', template: 'cursorrules.template' },
+  'Windsurf': { file: '.windsurfrules', template: 'cursorrules.template' },
+  'Codex': { file: 'AGENTS.md', template: null },  // AGENTS.md generated directly
+  'Kiro': { file: 'CLAUDE.md', template: 'CLAUDE.md.template' },
+  'Warp': { file: 'CLAUDE.md', template: 'CLAUDE.md.template' },
+  'Other': { file: 'CLAUDE.md', template: 'CLAUDE.md.template' },
+};
+
+// Stack → which skill directories to copy into stacks/
+const STACK_MAP = {
+  'Next.js + Supabase': ['nextjs', 'supabase'],
+  'Next.js + other': ['nextjs'],
+  'React + Node': [],
+  'Python': [],
+  'Other': [],
+};
+
+// Stack → display name for templates
+const STACK_LABEL = {
+  'Next.js + Supabase': 'Next.js, Supabase',
+  'Next.js + other': 'Next.js',
+  'React + Node': 'React, Node.js',
+  'Python': 'Python',
+  'Other': '',
+};
+
+module.exports = { IDE_MAP, STACK_MAP, STACK_LABEL };

package/src/index.js

@@ -0,0 +1,35 @@
+const { askQuestions } = require('./prompts');
+const { scaffold } = require('./scaffold');
+
+async function main() {
+  // Banner
+  console.log('');
+  console.log('  Baton — AI Orchestration Protocol v3.1');
+  console.log('');
+
+  // Prompts
+  const answers = await askQuestions();
+  console.log('');
+  console.log('  Setting up Baton...');
+  console.log('');
+
+  // Scaffold
+  const dest = process.cwd();
+  const results = scaffold(dest, answers);
+
+  // Success
+  for (const r of results) {
+    console.log(`  \u2713 ${r}`);
+  }
+
+  console.log('');
+  console.log('  Done! Next steps:');
+  console.log('    1. Open this folder in your AI coding tool');
+  console.log('    2. Tell the AI: "Read BATON_v3.1.md and begin"');
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/src/prompts.js

@@ -0,0 +1,54 @@
+const prompts = require('prompts');
+const path = require('path');
+
+async function askQuestions() {
+  // Exit gracefully on Ctrl+C
+  const onCancel = () => {
+    console.log('\nAborted.');
+    process.exit(0);
+  };
+
+  const answers = await prompts([
+    {
+      type: 'select',
+      name: 'tool',
+      message: 'What AI coding tool are you using?',
+      choices: [
+        { title: 'Claude Code', value: 'Claude Code' },
+        { title: 'Cursor', value: 'Cursor' },
+        { title: 'Windsurf', value: 'Windsurf' },
+        { title: 'Codex (OpenAI)', value: 'Codex' },
+        { title: 'Kiro', value: 'Kiro' },
+        { title: 'Warp', value: 'Warp' },
+        { title: 'Other', value: 'Other' },
+      ],
+    },
+    {
+      type: 'select',
+      name: 'stack',
+      message: "What's your primary stack?",
+      choices: [
+        { title: 'Next.js + Supabase', value: 'Next.js + Supabase' },
+        { title: 'Next.js + other', value: 'Next.js + other' },
+        { title: 'React + Node', value: 'React + Node' },
+        { title: 'Python', value: 'Python' },
+        { title: 'Other', value: 'Other' },
+      ],
+    },
+    {
+      type: 'text',
+      name: 'projectName',
+      message: 'Project name?',
+      initial: path.basename(process.cwd()),
+    },
+  ], { onCancel });
+
+  // If prompts were cancelled (empty object), exit
+  if (!answers.tool && answers.tool !== 0) {
+    process.exit(0);
+  }
+
+  return answers;
+}
+
+module.exports = { askQuestions };

package/src/scaffold.js

@@ -0,0 +1,193 @@
+const fs = require('fs');
+const path = require('path');
+const { IDE_MAP, STACK_MAP, STACK_LABEL } = require('./constants');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+function scaffold(dest, { tool, stack, projectName }) {
+  const results = [];
+
+  // 1. Check for existing BATON_v3.1.md
+  const batonDest = path.join(dest, 'BATON_v3.1.md');
+  if (fs.existsSync(batonDest)) {
+    console.log('\n  ! BATON_v3.1.md already exists — skipping (delete it first to overwrite)');
+  } else {
+    fs.copyFileSync(path.join(TEMPLATES_DIR, 'BATON_v3.1.md'), batonDest);
+    results.push('Copied BATON_v3.1.md');
+  }
+
+  // 2. Copy skills/
+  const skillsSrc = path.join(TEMPLATES_DIR, 'skills');
+  const skillsDest = path.join(dest, 'skills');
+
+  // Always copy core/ and patterns/
+  copyDir(path.join(skillsSrc, 'core'), path.join(skillsDest, 'core'));
+  copyDir(path.join(skillsSrc, 'patterns'), path.join(skillsDest, 'patterns'));
+
+  // Create domains/ (empty, for user to add)
+  fs.mkdirSync(path.join(skillsDest, 'domains'), { recursive: true });
+
+  // Copy stack-specific skills (each is a directory with SKILL.md)
+  const stackSkills = STACK_MAP[stack] || [];
+  fs.mkdirSync(path.join(skillsDest, 'stacks'), { recursive: true });
+  for (const skillDir of stackSkills) {
+    const src = path.join(skillsSrc, 'stacks', skillDir);
+    if (fs.existsSync(src)) {
+      copyDir(src, path.join(skillsDest, 'stacks', skillDir));
+    }
+  }
+
+  const coreCount = fs.readdirSync(path.join(skillsDest, 'core')).filter(
+    f => fs.statSync(path.join(skillsDest, 'core', f)).isDirectory()
+  ).length;
+  const stackCount = stackSkills.length;
+  const patternCount = fs.readdirSync(path.join(skillsDest, 'patterns')).filter(
+    f => fs.statSync(path.join(skillsDest, 'patterns', f)).isDirectory()
+  ).length;
+  results.push(`Copied skills/ (${coreCount} core + ${stackCount} stack + ${patternCount} pattern)`);
+
+  // 3. Create .ai-rules/ with stub files
+  const aiRulesDir = path.join(dest, '.ai-rules');
+  fs.mkdirSync(aiRulesDir, { recursive: true });
+  const stubs = {
+    'project.md': `# Project Rules — ${projectName}\n\n> AI will fill this during discovery session.\n`,
+    'tech-stack.md': `# Tech Stack — ${projectName}\n\n> AI will fill this during discovery session.\n`,
+    'patterns.md': `# Patterns & Quirks — ${projectName}\n\n> AI adds entries here as it discovers gotchas and solutions.\n`,
+    'structure.md': `# Project Structure — ${projectName}\n\n> AI will fill this once the project scaffolding is set up.\n`,
+  };
+  for (const [file, content] of Object.entries(stubs)) {
+    fs.writeFileSync(path.join(aiRulesDir, file), content);
+  }
+  results.push('Created .ai-rules/ (4 stub files)');
+
+  // 4. Create handoff/ with .gitkeep
+  const handoffDir = path.join(dest, 'handoff');
+  fs.mkdirSync(handoffDir, { recursive: true });
+  fs.writeFileSync(path.join(handoffDir, '.gitkeep'), '');
+  results.push('Created handoff/');
+
+  // 5. Create IDE config file from template
+  const ide = IDE_MAP[tool] || IDE_MAP['Other'];
+  const stackLabel = STACK_LABEL[stack] || '';
+
+  if (ide.template) {
+    // Template-based IDE config (Claude Code, Cursor, Windsurf, etc.)
+    const templatePath = path.join(TEMPLATES_DIR, 'ide', ide.template);
+    let templateContent = fs.readFileSync(templatePath, 'utf-8');
+
+    templateContent = templateContent
+      .replace(/\{\{PROJECT_NAME\}\}/g, projectName)
+      .replace(/\{\{STACK\}\}/g, stackLabel)
+      .replace(/\{\{CURRENT_SESSION\}\}/g, '1')
+      .replace(/\{\{NEXT_SESSION\}\}/g, '2')
+      .replace(/\{\{BUILD_COMMAND\}\}/g, 'npm run build')
+      .replace(/\{\{DEV_COMMAND\}\}/g, 'npm run dev')
+      .replace(/\{\{TYPECHECK_COMMAND\}\}/g, 'npx tsc --noEmit')
+      .replace(/\{\{PROJECT_RULES\}\}/g, '<!-- AI will add project-specific rules here -->');
+
+    fs.writeFileSync(path.join(dest, ide.file), templateContent);
+    results.push(`Created ${ide.file}`);
+  } else {
+    // Codex — uses AGENTS.md directly (already generated in step 6)
+    results.push('Using AGENTS.md as IDE config (Codex)');
+  }
+
+  // 6. Generate AGENTS.md (universal standard for AI coding agents)
+  const agentsMd = generateAgentsMd(projectName, stackLabel);
+  fs.writeFileSync(path.join(dest, 'AGENTS.md'), agentsMd);
+  results.push('Generated AGENTS.md');
+
+  // 7. Create PROGRESS.md, BACKLOG.md, FEATURES.md
+  fs.writeFileSync(path.join(dest, 'PROGRESS.md'),
+    `# Progress — ${projectName}\n\n## Sessions\n\n_No sessions yet. AI will log progress here._\n`);
+  fs.writeFileSync(path.join(dest, 'BACKLOG.md'),
+    `# Backlog — ${projectName}\n\n_Deferred items go here. AI adds items during sessions._\n`);
+  fs.writeFileSync(path.join(dest, 'FEATURES.md'),
+    `# Features — ${projectName}\n\n_User-facing feature documentation. AI updates this as features ship._\n`);
+  results.push('Created PROGRESS.md, BACKLOG.md, FEATURES.md');
+
+  return results;
+}
+
+function generateAgentsMd(projectName, stack) {
+  const stackLine = stack ? `- **Stack:** ${stack}` : '- **Stack:** (to be determined during Session Zero)';
+  return `# AGENTS.md
+
+This file provides guidance to AI coding agents working with this repository.
+
+## Project Overview
+
+${projectName} — bootstrapped with the Baton protocol.
+
+${stackLine}
+- **Protocol:** Baton v3.1 (AI orchestration protocol)
+- **Architecture:** See \`.ai-rules/\` for project context (generated during Session Zero)
+
+## Getting Started
+
+This project uses the Baton protocol for AI-assisted development.
+
+1. Read \`BATON_v3.1.md\` — the orchestration protocol
+2. Read \`.ai-rules/\` — project context files (AI-generated)
+3. Read \`skills/\` — curated best practices for this stack
+4. Check \`handoff/\` — session handoff files for continuity
+
+## Build & Development Commands
+
+\`\`\`bash
+# Install dependencies
+npm install
+
+# Development
+npm run dev
+
+# Build
+npm run build
+\`\`\`
+
+## Code Style & Conventions
+
+See \`.ai-rules/patterns.md\` for project-specific patterns.
+See \`skills/core/\` for universal rules (security, testing, anti-overengineering).
+
+## Project Structure
+
+\`\`\`
+BATON_v3.1.md          # AI orchestration protocol
+.ai-rules/             # Project context (AI-generated)
+skills/                # Best practice skills
+  core/                # Universal rules
+  stacks/              # Stack-specific patterns
+  patterns/            # Implementation patterns
+handoff/               # Session handoff files
+PROGRESS.md            # Session progress log
+BACKLOG.md             # Deferred items
+\`\`\`
+
+## Agent Boundaries
+
+This project follows the Baton protocol. Key rules:
+- Read BATON_v3.1.md before starting work
+- Check skills/ before web searching
+- Document discoveries in .ai-rules/patterns.md
+- Create handoff files at session end
+- Update PROGRESS.md after each session
+`;
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  if (!fs.existsSync(src)) return;
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = { scaffold };