create-agent-room 1.2.1

package/lib/session-utils.js

@@ -0,0 +1,213 @@
+'use strict';
+
+/**
+ * Session state utilities for agents
+ * Provides helpers to create, read, and manage session logs
+ *
+ * Usage:
+ *   const session = require('./.agent-room/utils/session-utils');
+ *   const log = session.createLog({
+ *     goal: 'Add user API',
+ *     classification: 'Feature'
+ *   });
+ *   log.addAction('Designed database schema');
+ *   log.addFile('created', 'schema.sql');
+ *   log.save();
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SESSION_DIR = path.join(process.cwd(), '.agent-room', 'sessions');
+
+function ensureSessionDir() {
+  if (!fs.existsSync(SESSION_DIR)) {
+    fs.mkdirSync(SESSION_DIR, { recursive: true });
+  }
+}
+
+function generateTimestamp() {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  const hours = String(now.getHours()).padStart(2, '0');
+  const minutes = String(now.getMinutes()).padStart(2, '0');
+  return `${year}-${month}-${day}-${hours}-${minutes}`;
+}
+
+class SessionLog {
+  constructor(options = {}) {
+    this.timestamp = generateTimestamp();
+    this.date = new Date().toISOString().slice(0, 16).replace('T', ' ');
+    this.agent = options.agent || 'Unknown Agent';
+    this.classification = options.classification || 'Enhancement';
+    this.goal = options.goal || '';
+    this.actions = [];
+    this.files = { read: [], created: [], modified: [] };
+    this.tests = { command: '', result: '' };
+    this.decisions = [];
+    this.outcome = 'In Progress';
+    this.handoffNote = '';
+    this.topic = options.topic || 'session';
+  }
+
+  addAction(description) {
+    this.actions.push(description);
+    return this;
+  }
+
+  addFile(type, filePath) {
+    if (['read', 'created', 'modified'].includes(type)) {
+      this.files[type].push(filePath);
+    }
+    return this;
+  }
+
+  addDecision(decision) {
+    this.decisions.push(decision);
+    return this;
+  }
+
+  setTests(command, result) {
+    this.tests.command = command;
+    this.tests.result = result;
+    return this;
+  }
+
+  complete(handoffNote = '') {
+    this.outcome = 'Completed';
+    this.handoffNote = handoffNote;
+    return this;
+  }
+
+  handOff(handoffNote = '') {
+    this.outcome = 'Handed Off';
+    this.handoffNote = handoffNote;
+    return this;
+  }
+
+  toMarkdown() {
+    const files = [];
+    if (this.files.read.length > 0) {
+      files.push(`- Read: ${this.files.read.join(', ')}`);
+    }
+    if (this.files.created.length > 0) {
+      files.push(`- Created: ${this.files.created.join(', ')}`);
+    }
+    if (this.files.modified.length > 0) {
+      files.push(`- Modified: ${this.files.modified.join(', ')}`);
+    }
+
+    const actions = this.actions.map((a, i) => `${i + 1}. ${a}`).join('\n');
+
+    const decisions = this.decisions.length > 0 ? this.decisions.map((d) => `- ${d}`).join('\n') : 'None documented.';
+
+    const handoff = this.handoffNote ? `\n**Handoff note (if applicable):**\n${this.handoffNote}` : '';
+
+    return `# Session Log: ${this.topic}
+
+**Date:** ${this.date}
+**Agent:** ${this.agent}
+**Classification:** ${this.classification}
+
+## Goal
+${this.goal}
+
+## Files touched
+${files.length > 0 ? files.join('\n') : 'None'}
+
+## Actions taken
+${actions}
+
+## Tests run
+Command: ${this.tests.command}
+Result: ${this.tests.result}
+
+## Decisions made
+${decisions}
+
+## Outcome
+**Status:** ${this.outcome}${handoff}
+`;
+  }
+
+  toJSON() {
+    return {
+      timestamp: this.timestamp,
+      date: this.date,
+      agent: this.agent,
+      classification: this.classification,
+      goal: this.goal,
+      actions: this.actions,
+      files: this.files,
+      tests: this.tests,
+      decisions: this.decisions,
+      outcome: this.outcome,
+      handoffNote: this.handoffNote
+    };
+  }
+
+  save(format = 'markdown') {
+    ensureSessionDir();
+
+    const fileName = `${this.timestamp}-${this.topic.replace(/\s+/g, '-').toLowerCase()}`;
+    const ext = format === 'json' ? '.json' : '.md';
+    const filePath = path.join(SESSION_DIR, fileName + ext);
+
+    let content;
+    if (format === 'json') {
+      content = JSON.stringify(this.toJSON(), null, 2);
+    } else {
+      content = this.toMarkdown();
+    }
+
+    fs.writeFileSync(filePath, content, 'utf8');
+    return { path: filePath, relativePath: path.relative(process.cwd(), filePath) };
+  }
+}
+
+/**
+ * Create a new session log
+ * @param {Object} options - Configuration
+ * @param {string} options.goal - The session goal
+ * @param {string} options.agent - Agent name (default: "Unknown Agent")
+ * @param {string} options.classification - Bug, Enhancement, Feature, or Product (default: "Enhancement")
+ * @param {string} options.topic - Topic for filename (default: "session")
+ * @returns {SessionLog}
+ */
+function createLog(options = {}) {
+  return new SessionLog(options);
+}
+
+/**
+ * List all session logs
+ * @returns {Array} List of session log paths
+ */
+function listSessions() {
+  ensureSessionDir();
+  if (!fs.existsSync(SESSION_DIR)) {
+    return [];
+  }
+  return fs.readdirSync(SESSION_DIR)
+    .filter((f) => f.endsWith('.md') || f.endsWith('.json'))
+    .map((f) => path.join(SESSION_DIR, f));
+}
+
+/**
+ * Get the latest session log
+ * @returns {string|null} Path to latest session log or null if none exist
+ */
+function getLatestSession() {
+  const sessions = listSessions();
+  if (sessions.length === 0) return null;
+  return sessions.sort().reverse()[0];
+}
+
+module.exports = {
+  createLog,
+  SessionLog,
+  listSessions,
+  getLatestSession,
+  generateTimestamp
+};

package/lib/sync.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function isGitDirty(target, relativePath) {
+  try {
+    const res = execSync(`git status --porcelain "${relativePath}"`, {
+      cwd: target,
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).toString();
+    return res.trim().length > 0;
+  } catch (err) {
+    return false;
+  }
+}
+
+function checkSkillsSync(target) {
+  const srcDir = path.join(target, '.agent-room', 'skills');
+  const outOfSync = [];
+  if (!fs.existsSync(srcDir)) {
+    return outOfSync;
+  }
+
+  for (const file of fs.readdirSync(srcDir)) {
+    if (!file.endsWith('.md')) continue;
+    const skillName = file.replace(/\.md$/, '');
+    const dest = path.join(target, '.claude', 'skills', skillName, 'SKILL.md');
+    const relativeDest = path.relative(target, dest);
+
+    if (!fs.existsSync(dest)) {
+      outOfSync.push({ path: relativeDest, reason: 'missing' });
+      continue;
+    }
+
+    const srcContent = fs.readFileSync(path.join(srcDir, file), 'utf8');
+    const destContent = fs.readFileSync(dest, 'utf8');
+    if (srcContent !== destContent) {
+      outOfSync.push({ path: relativeDest, reason: 'different' });
+    }
+  }
+  return outOfSync;
+}
+
+function syncSkillsToClaude(target) {
+  const srcDir = path.join(target, '.agent-room', 'skills');
+  const results = [];
+  for (const file of fs.readdirSync(srcDir)) {
+    if (!file.endsWith('.md')) continue;
+    const skillName = file.replace(/\.md$/, '');
+    const dest = path.join(target, '.claude', 'skills', skillName, 'SKILL.md');
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, fs.readFileSync(path.join(srcDir, file), 'utf8'));
+    results.push({ path: path.relative(target, dest) });
+  }
+  return results;
+}
+
+function runSync(target, args) {
+  const checkOnly = !!(args && args.check);
+  const force = !!(args && args.force);
+
+  const configPath = path.join(target, '.agent-room.json');
+  let tools = [];
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config && Array.isArray(config.tools)) {
+        tools = config.tools;
+      }
+    } catch (err) {
+      console.warn(`Warning: Failed to parse .agent-room.json: ${err.message}`);
+    }
+  }
+
+  const agentRoomDir = path.join(target, '.agent-room', 'skills');
+  if (!fs.existsSync(agentRoomDir)) {
+    throw new Error(`No .agent-room/skills/ found in ${target} - run "create-agent-room init" first.`);
+  }
+
+  if (tools.length === 0) {
+    if (fs.existsSync(path.join(target, 'CLAUDE.md')) || fs.existsSync(path.join(target, '.claude'))) {
+      tools.push('claude');
+    }
+  }
+
+  if (!tools.includes('claude')) {
+    console.log('No tools requiring sync found in project configuration - nothing to sync.');
+    return;
+  }
+
+  if (checkOnly) {
+    console.log('Checking if mirrored skills are out of sync...');
+    const outOfSync = checkSkillsSync(target);
+    if (outOfSync.length > 0) {
+      for (const item of outOfSync) {
+        console.log(`  out-of-sync  ${item.path} (${item.reason})`);
+      }
+      console.error('\nError: Mirrored skills are out of sync. Run "create-agent-room sync" to update them.');
+      process.exitCode = 1;
+    } else {
+      console.log('All mirrored skills are up to date.');
+    }
+    return;
+  }
+
+  const srcDir = path.join(target, '.agent-room', 'skills');
+  const results = [];
+  for (const file of fs.readdirSync(srcDir)) {
+    if (!file.endsWith('.md')) continue;
+    const skillName = file.replace(/\.md$/, '');
+    const dest = path.join(target, '.claude', 'skills', skillName, 'SKILL.md');
+    const relativeDest = path.relative(target, dest);
+
+    if (fs.existsSync(dest) && !force) {
+      if (isGitDirty(target, relativeDest)) {
+        console.log(`  skipped  ${relativeDest} (has unsaved modifications, use --force to overwrite)`);
+        results.push({ path: relativeDest, written: false, reason: 'dirty' });
+        continue;
+      }
+    }
+
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, fs.readFileSync(path.join(srcDir, file), 'utf8'));
+    console.log(`  synced  ${relativeDest}`);
+    results.push({ path: relativeDest, written: true });
+  }
+
+  const skipped = results.filter((r) => !r.written && r.reason === 'dirty');
+  if (skipped.length > 0) {
+    console.warn(`\nWarning: ${skipped.length} mirrored file(s) had unsaved modifications and were skipped to prevent overwriting your edits. Use --force to discard modifications.`);
+  } else {
+    console.log('\nSynced .agent-room/skills/* into .claude/skills/* (source of truth is .agent-room/skills/).');
+  }
+}
+
+module.exports = { runSync, syncSkillsToClaude, checkSkillsSync, isGitDirty };

package/lib/validate.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { green, yellow, red, cyan, bold } = require('./color');
+
+function runValidate(target) {
+  console.log(bold(`Running agent-room integrity checks in: ${cyan(target)}\n`));
+
+  let failed = false;
+  const errors = [];
+  const warnings = [];
+
+  const checkFile = (relPath, required = true) => {
+    const fullPath = path.join(target, relPath);
+    if (!fs.existsSync(fullPath)) {
+      if (required) {
+        errors.push(`Missing required file: ${relPath}`);
+        failed = true;
+      } else {
+        warnings.push(`Recommended file not found: ${relPath}`);
+      }
+      return false;
+    }
+    return true;
+  };
+
+  const checkDir = (relPath, required = true) => {
+    const fullPath = path.join(target, relPath);
+    if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isDirectory()) {
+      if (required) {
+        errors.push(`Missing required directory: ${relPath}`);
+        failed = true;
+      } else {
+        warnings.push(`Recommended directory not found: ${relPath}`);
+      }
+      return false;
+    }
+    return true;
+  };
+
+  // 1. Check Directory and Files Structure
+  checkFile('AGENTS.md');
+  checkFile('.agent-room.json');
+  checkDir('.agent-room');
+
+  if (fs.existsSync(path.join(target, '.agent-room'))) {
+    checkFile('.agent-room/principles.md');
+    checkFile('.agent-room/workflow-classifier.md');
+    checkFile('.agent-room/guardrails.md');
+    checkFile('.agent-room/guardrails.json');
+    checkFile('.agent-room/anti-patterns.md');
+    checkFile('.agent-room/decisions.md');
+
+    // Check coordination structure
+    if (checkDir('.agent-room/coordination')) {
+      checkFile('.agent-room/coordination/handoff-protocol.md');
+      checkFile('.agent-room/coordination/scope-boundaries.md');
+      checkFile('.agent-room/coordination/session-log-format.md');
+    }
+
+    checkDir('.agent-room/sessions');
+
+    // 2. Validate guardrails.json Configuration
+    const guardrailsPath = path.join(target, '.agent-room/guardrails.json');
+    if (fs.existsSync(guardrailsPath)) {
+      try {
+        const content = fs.readFileSync(guardrailsPath, 'utf8');
+        const data = JSON.parse(content);
+
+        const requiredArrays = ['protectedPaths', 'requireApprovalFor', 'forbiddenActions'];
+        for (const prop of requiredArrays) {
+          if (!data[prop]) {
+            errors.push(`guardrails.json is missing required property: ${prop}`);
+            failed = true;
+          } else if (!Array.isArray(data[prop])) {
+            errors.push(`guardrails.json property "${prop}" must be an array`);
+            failed = true;
+          }
+        }
+      } catch (err) {
+        errors.push(`Failed to parse guardrails.json: ${err.message}`);
+        failed = true;
+      }
+    }
+
+    // 3. Lint Markdown Skill Files
+    const skillsDir = path.join(target, '.agent-room/skills');
+    if (fs.existsSync(skillsDir) && fs.statSync(skillsDir).isDirectory()) {
+      const files = fs.readdirSync(skillsDir).filter((f) => f.endsWith('.md'));
+      if (files.length === 0) {
+        warnings.push('No skill files found under .agent-room/skills/');
+      }
+
+      for (const file of files) {
+        const filePath = path.join(skillsDir, file);
+        try {
+          const content = fs.readFileSync(filePath, 'utf8');
+
+          // Parse YAML Frontmatter
+          const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---/;
+          const match = content.match(fmRegex);
+
+          if (!match) {
+            errors.push(`Skill file "${path.join('.agent-room/skills', file)}" is missing valid YAML frontmatter delimiters (---)`);
+            failed = true;
+            continue;
+          }
+
+          const fmContent = match[1];
+          const lines = fmContent.split(/\r?\n/);
+          const metadata = {};
+
+          for (const line of lines) {
+            const separatorIndex = line.indexOf(':');
+            if (separatorIndex !== -1) {
+              const key = line.slice(0, separatorIndex).trim();
+              const val = line.slice(separatorIndex + 1).trim();
+              metadata[key] = val;
+            }
+          }
+
+          if (!metadata.name) {
+            errors.push(`Skill file "${path.join('.agent-room/skills', file)}" is missing the "name" metadata attribute in its frontmatter`);
+            failed = true;
+          } else {
+            const cleanName = metadata.name.replace(/['"]/g, '').trim();
+            if (!cleanName) {
+              errors.push(`Skill file "${path.join('.agent-room/skills', file)}" has an empty "name" attribute`);
+              failed = true;
+            }
+          }
+
+          if (!metadata.description) {
+            errors.push(`Skill file "${path.join('.agent-room/skills', file)}" is missing the "description" metadata attribute in its frontmatter`);
+            failed = true;
+          } else {
+            const cleanDesc = metadata.description.replace(/['"]/g, '').trim();
+            if (!cleanDesc) {
+              errors.push(`Skill file "${path.join('.agent-room/skills', file)}" has an empty "description" attribute`);
+              failed = true;
+            }
+          }
+        } catch (err) {
+          errors.push(`Failed to read or parse skill file ${file}: ${err.message}`);
+          failed = true;
+        }
+      }
+    }
+  }
+
+  // Output Results
+  if (warnings.length > 0) {
+    console.log(bold(yellow('Warnings:')));
+    for (const w of warnings) {
+      console.log(yellow(`  ⚠️  ${w}`));
+    }
+    console.log('');
+  }
+
+  if (failed) {
+    console.log(bold(red('Validation FAILED:')));
+    for (const e of errors) {
+      console.log(red(`  ❌  ${e}`));
+    }
+    console.log('');
+    process.exitCode = 1;
+  } else {
+    console.log(bold(green('Validation PASSED!')));
+    console.log(green('  ✅  All core files are present.'));
+    console.log(green('  ✅  guardrails.json is valid and populated.'));
+    console.log(green('  ✅  All skills have valid frontmatter metadata.'));
+    console.log('');
+  }
+}
+
+module.exports = {
+  runValidate
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "create-agent-room",
+  "version": "1.2.1",
+  "description": "Scaffold an LLM-agent-friendly project structure: AGENTS.md, principles, workflow classifier, anti-patterns/decisions logs, and core skills (brainstorming, writing-plans, TDD, systematic debugging, verification-before-completion).",
+  "bin": {
+    "create-agent-room": "bin/cli.js"
+  },
+  "main": "lib/init.js",
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "examples",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sipandey/create-agent-room.git"
+  },
+  "homepage": "https://github.com/sipandey/create-agent-room#readme",
+  "bugs": {
+    "url": "https://github.com/sipandey/create-agent-room/issues"
+  },
+  "keywords": [
+    "llm",
+    "agents",
+    "ai-agents",
+    "claude",
+    "cursor",
+    "windsurf",
+    "scaffold",
+    "cli",
+    "agents-md",
+    "governance"
+  ],
+  "author": "Siddharth Pandey",
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0"
+  }
+}

package/templates/.agent-room/anti-patterns.md

@@ -0,0 +1,22 @@
+# Anti-Patterns Log — {{PROJECT_NAME}}
+
+Negative knowledge: things that have already gone wrong here, so nobody
+(human or agent) repeats them. One avoided bug is worth more than one
+polished example — keep entries short and concrete.
+
+Append a new entry every time:
+- a bug slips through and you find the root cause,
+- an approach seemed reasonable but turned out wrong,
+- a fix gets reverted because it only patched a symptom.
+
+## Format
+
+```
+### YYYY-MM-DD — short title
+
+**What happened:** one or two sentences.
+**Root cause:** the actual cause, not the symptom.
+**Avoid:** the concrete rule that would have prevented it.
+```
+
+<!-- Entries go below this line, newest first. -->

package/templates/.agent-room/coordination/handoff-protocol.md

@@ -0,0 +1,60 @@
+# Agent Handoff Protocol
+
+## Overview
+
+Modern agent workflows often involve multiple sessions, orchestrators,
+and sub-agents. A handoff protocol ensures that context isn't lost when
+one agent finishes its turn and another begins. The receiving agent
+must not have to guess what was already done or what assumptions were
+made.
+
+## The iron law
+
+```
+NEVER END A SESSION WITH "WIP" — ALWAYS SERIALIZE STATE
+```
+
+If an agent session is ending before the full feature is complete, it
+must serialize its state so the next session can pick up exactly where
+it left off.
+
+## The Handoff Note
+
+When handing off work, write a handoff note (either in the chat, in a
+PR description, or in the session log). It must include:
+
+1.  **Completed:** What is definitively finished and verified.
+2.  **In Progress:** What is partially built but not yet working.
+3.  **Blocked On:** What is preventing completion (missing credentials,
+    unclear requirements, failing dependency).
+4.  **Assumptions:** Any decisions made during the session that the next
+    agent needs to know.
+
+### Example Handoff Note
+
+```markdown
+**Completed:**
+- User model and database migration.
+- `POST /register` route (handler skeleton exists, validation not started).
+
+**In Progress:**
+- Email verification service.
+
+**Blocked On:**
+- Need SMTP credentials in the `.env` file to test the email service.
+
+**Assumptions:**
+- Using `bcrypt` for passwords per decision in `.agent-room/decisions.md`.
+```
+
+## Receiving Handoffs
+
+When you are the receiving agent (starting a new session):
+
+1.  **Re-verify, don't trust:** Do not blindly trust the previous agent's
+    "Completed" list. Run the tests. Check the diff. Verify the state
+    yourself.
+2.  **Read decisions:** Check `.agent-room/decisions.md` to understand
+    *why* the previous agent made the choices it did.
+3.  **Address blockers first:** If the handoff note lists blockers,
+    resolve them (or escalate them to the user) before writing new code.