syntropic 0.3.0 → 0.3.2

package/README.md

@@ -0,0 +1,95 @@
+# syntropic
+
+A development methodology for AI-assisted coding. Works with **Claude Code**, **Cursor**, **Windsurf**, and **GitHub Copilot**.
+
+One command gives your AI coding tools a disciplined development pipeline — so they research before they plan, plan before they build, and review before they ship.
+
+## Quick Start
+
+```bash
+npx syntropic init my-project
+```
+
+Or add to an existing project:
+
+```bash
+cd my-project
+npx syntropic init
+```
+
+You'll be asked which AI tools you use. The CLI generates the right instruction files for each:
+
+| Tool | File Generated |
+|------|---------------|
+| Claude Code | `CLAUDE.md` + `.claude/commands/` agents |
+| Cursor | `.cursorrules` |
+| Windsurf | `.windsurfrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+## What You Get
+
+**Evergreen Rules (EG1-EG9)** — a portable set of development principles:
+
+- **EG1: Pre-Flight Loop** — build must pass, no localhost refs, verify after deploy
+- **EG2: Ship and Iterate** — bias to action, only pause for destructive/expensive/irreversible
+- **EG3: Hypothesis-Driven Debugging** — state hypothesis, test without code changes, only code if confirmed
+- **EG7: Implementation Pipeline** — scale process to task size (Full / Lightweight / Minimum cycle)
+- **EG8: Live Site Testing** — test page first, promote to production with approval
+- **EG9: Session Continuity** — re-read rules on reset, verify state before proceeding
+
+**Generic Agents** (Claude Code) — dev, qa, research, plan, devops, security
+
+**Health Check** — daily GitHub Action with auto-remediation (npm audit fix PRs)
+
+**PRISM Methodology** — track efficiency: estimate cost vs. value before complex tasks, learn what works
+
+## Commands
+
+```bash
+# Scaffold a new project (interactive)
+npx syntropic init my-project
+
+# Non-interactive with flags
+npx syntropic init my-project --tools claude,cursor --name "My App" --domain myapp.com --test-url /staging --prod-url /
+
+# Add a tool to an existing project
+npx syntropic add cursor
+npx syntropic add windsurf copilot
+
+# Run a local health check (EG1 pre-flight)
+npx syntropic health
+```
+
+## Existing Projects
+
+Running `syntropic init` in a project that already has a `CLAUDE.md` or `.cursorrules` will **append** the methodology to your existing file — it never overwrites. A `<!-- syntropic -->` marker prevents duplicate rules on re-runs.
+
+## The Methodology
+
+The core idea: AI coding tools are powerful but undisciplined. Without rules, they jump straight to code, skip investigation, retry failed approaches, and introduce regressions.
+
+Syntropic gives them a process:
+
+1. **Research** — understand the problem before proposing solutions
+2. **Plan** — break work into sequenced steps, identify risks
+3. **Build** — implement with minimal changes, match existing patterns
+4. **Review** — check security, quality, and correctness
+5. **Verify** — test on a live URL, not just locally
+
+Scale the process to the task. A typo fix doesn't need research. A new feature does.
+
+## Philosophy
+
+- **Ship and iterate** — momentum over perfection
+- **Hypothesis-driven** — test before you code
+- **Outcome-aligned** — if the user succeeds, do we succeed?
+- **No workarounds** — no bypasses, no "fix later", no shortcuts without approval
+
+## Links
+
+- [Website](https://www.syntropicworks.com)
+- [GitHub](https://github.com/petercholford-ship-it/syntropicworks)
+
+## License
+
+MIT

package/bin/syntropic.js

@@ -15,6 +15,7 @@ const command = args[0];
 
 const COMMANDS = {
   init: () => require('../commands/init'),
+  add: () => require('../commands/add'),
   health: () => require('../commands/health'),
 };
 
@@ -32,6 +33,7 @@ if (!command || args.includes('--help') || args.includes('-h')) {
 
   Usage:
     syntropic init [project-name]   Scaffold a new project with the Syntropic pipeline
+    syntropic add <tool> [tool...]  Add support for another AI tool (cursor, windsurf, copilot, claude)
     syntropic health                Run a local health check
     syntropic --version             Show version
     syntropic --help                Show this help

package/commands/add.js

@@ -0,0 +1,195 @@
+/**
+ * syntropic add <tool> [tool...]
+ *
+ * Adds Syntropic pipeline support for additional AI coding tools
+ * to an existing project. Creates new instruction files or appends
+ * rules to existing ones.
+ *
+ * Examples:
+ *   syntropic add cursor
+ *   syntropic add cursor windsurf copilot
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+const TOOLS = {
+  claude:   { label: 'Claude Code',      file: 'CLAUDE.md',                        hasAgents: true },
+  cursor:   { label: 'Cursor',           file: '.cursorrules',                     hasAgents: false },
+  windsurf: { label: 'Windsurf',         file: '.windsurfrules',                   hasAgents: false },
+  copilot:  { label: 'GitHub Copilot',   file: '.github/copilot-instructions.md',  hasAgents: false },
+};
+
+const TEMPLATE_MAP = {
+  claude:   ['CLAUDE.md',                     'claude-append.template'],
+  cursor:   ['cursorrules.template',          'tool-append.template'],
+  windsurf: ['windsurfrules.template',        'tool-append.template'],
+  copilot:  ['copilot-instructions.template', 'tool-append.template'],
+};
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function hasSyntropicMarker(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  return fs.readFileSync(filePath, 'utf8').includes('<!-- syntropic -->');
+}
+
+function renderTemplate(templateFile, replacements) {
+  const templatePath = path.join(TEMPLATES_DIR, templateFile);
+  if (!fs.existsSync(templatePath)) return null;
+  let content = fs.readFileSync(templatePath, 'utf8');
+  for (const [key, value] of Object.entries(replacements)) {
+    content = content.replace(new RegExp(key, 'g'), value);
+  }
+  return content;
+}
+
+function writeOrAppend(fullTemplate, appendTemplate, destPath, replacements) {
+  const relPath = path.relative(process.cwd(), destPath);
+  const destDir = path.dirname(destPath);
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+
+  if (!fs.existsSync(destPath)) {
+    const content = renderTemplate(fullTemplate, replacements);
+    if (content) fs.writeFileSync(destPath, content, 'utf8');
+    console.log(`  create  ${relPath}`);
+    return 'created';
+  } else if (hasSyntropicMarker(destPath)) {
+    console.log(`  skip  ${relPath} (Syntropic rules already present)`);
+    return 'skipped';
+  } else {
+    const appendContent = renderTemplate(appendTemplate, replacements);
+    if (appendContent) fs.appendFileSync(destPath, appendContent, 'utf8');
+    console.log(`  append  ${relPath} (added Syntropic pipeline rules)`);
+    return 'appended';
+  }
+}
+
+function detectExistingConfig(targetDir) {
+  // Try to read project config from existing Syntropic instruction files
+  for (const tool of Object.values(TOOLS)) {
+    const filePath = path.join(targetDir, tool.file);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const config = {};
+
+      // Extract test URL
+      const testMatch = content.match(/Test page:\s*(\S+)/);
+      if (testMatch) config.testUrl = testMatch[1];
+
+      // Extract prod URL
+      const prodMatch = content.match(/Production:\s*(\S+)/);
+      if (prodMatch) config.prodUrl = prodMatch[1];
+
+      // Extract domain
+      const domainMatch = content.match(/Production domain:\*?\*?\s*(\S+)/);
+      if (domainMatch) config.prodDomain = domainMatch[1];
+
+      // Extract project name
+      const nameMatch = content.match(/## Project:\s*(.+)/);
+      if (nameMatch) config.projectName = nameMatch[1].trim();
+
+      if (Object.keys(config).length > 0) return config;
+    }
+  }
+  return null;
+}
+
+async function run(args) {
+  const validTools = Object.keys(TOOLS);
+  const requestedTools = args.map(a => a.toLowerCase()).filter(a => validTools.includes(a));
+
+  if (requestedTools.length === 0) {
+    console.log(`
+  syntropic add — Add AI tool support to an existing project
+
+  Usage:
+    syntropic add cursor                Add Cursor support
+    syntropic add windsurf copilot      Add multiple tools
+    syntropic add claude                Add Claude Code support
+
+  Available tools: ${validTools.join(', ')}
+`);
+    process.exit(0);
+  }
+
+  const targetDir = process.cwd();
+  console.log(`\n  syntropic add — Adding ${requestedTools.map(t => TOOLS[t].label).join(', ')}\n`);
+
+  // Try to detect project config from existing instruction files
+  const existing = detectExistingConfig(targetDir);
+  const isInteractive = process.stdin.isTTY !== false;
+
+  const dirName = path.basename(targetDir);
+  const projectName = existing?.projectName || (isInteractive ? await ask(`  Project name (${dirName}): `) : '') || dirName;
+  const testUrl = existing?.testUrl || (isInteractive ? await ask('  Test page URL path (e.g. /test): ') : '') || '/test';
+  const prodUrl = existing?.prodUrl || (isInteractive ? await ask('  Production URL path (e.g. /): ') : '') || '/';
+  const prodDomain = existing?.prodDomain || (isInteractive ? await ask('  Production domain (e.g. example.com): ') : '') || 'example.com';
+
+  if (existing) {
+    console.log(`  Detected config: ${projectName} (${prodDomain})\n`);
+  }
+
+  const replacements = {
+    '\\{\\{PROJECT_NAME\\}\\}': projectName,
+    '\\{\\{TEST_URL\\}\\}': testUrl,
+    '\\{\\{PROD_URL\\}\\}': prodUrl,
+    '\\{\\{PROD_DOMAIN\\}\\}': prodDomain,
+  };
+
+  for (const tool of requestedTools) {
+    const [fullTpl, appendTpl] = TEMPLATE_MAP[tool];
+    const destPath = path.join(targetDir, TOOLS[tool].file);
+    writeOrAppend(fullTpl, appendTpl, destPath, replacements);
+  }
+
+  // If adding Claude, also copy agents
+  if (requestedTools.includes('claude')) {
+    const claudeDir = path.join(targetDir, '.claude');
+    const templateClaudeDir = path.join(TEMPLATES_DIR, '.claude');
+    if (fs.existsSync(templateClaudeDir)) {
+      const { copyDir } = require('./init');
+      if (typeof copyDir === 'function') {
+        copyDir(templateClaudeDir, claudeDir);
+      } else {
+        // Inline copy for agents
+        const commandsDir = path.join(templateClaudeDir, 'commands');
+        const destCommandsDir = path.join(claudeDir, 'commands');
+        if (fs.existsSync(commandsDir)) {
+          if (!fs.existsSync(destCommandsDir)) fs.mkdirSync(destCommandsDir, { recursive: true });
+          for (const file of fs.readdirSync(commandsDir)) {
+            const dest = path.join(destCommandsDir, file);
+            if (!fs.existsSync(dest)) {
+              fs.copyFileSync(path.join(commandsDir, file), dest);
+              console.log(`  create  ${path.relative(process.cwd(), dest)}`);
+            }
+          }
+        }
+        // Copy EVERGREEN_RULES.md
+        const egSrc = path.join(templateClaudeDir, 'EVERGREEN_RULES.md');
+        const egDest = path.join(claudeDir, 'EVERGREEN_RULES.md');
+        if (fs.existsSync(egSrc) && !fs.existsSync(egDest)) {
+          fs.copyFileSync(egSrc, egDest);
+          console.log(`  create  ${path.relative(process.cwd(), egDest)}`);
+        }
+      }
+    }
+  }
+
+  console.log(`
+  Done! Added: ${requestedTools.map(t => TOOLS[t].label).join(', ')}
+`);
+}
+
+module.exports = run;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntropic",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Philosophy-as-code development pipeline for Claude Code, Cursor, Windsurf, and GitHub Copilot.",
   "bin": {
     "syntropic": "./bin/syntropic.js"