syntropic 0.4.0 → 0.5.0

package/bin/syntropic.js

@@ -33,20 +33,21 @@ 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 add <tool> [tool...]  Add support for another AI tool
     syntropic health                Run a local health check
     syntropic --version             Show version
     syntropic --help                Show this help
 
   What you get:
-    - Instruction files for Claude Code, Cursor, Windsurf, and/or GitHub Copilot
+    - Instruction files for Claude Code, Cursor, Windsurf, GitHub Copilot, and/or OpenAI Codex
+    - SKILL.md for automatic discovery by Claude Code and Codex
     - Evergreen Rules (EG1-EG9) — a disciplined dev pipeline
     - Generic agents: dev, qa, research, plan, devops, security (Claude Code)
     - Daily health check workflow with auto-remediation
     - PRISM efficiency tracking methodology
 
   Flags (init):
-    --tools claude,cursor,windsurf,copilot   Select AI tools (default: all)
+    --tools claude,cursor,windsurf,copilot,codex   Select AI tools (default: all)
     --name "My Project"                      Project name
     --domain example.com                     Production domain
     --test-url /test                         Test page path

package/commands/add.js

@@ -17,10 +17,11 @@ 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 },
+  claude:   { label: 'Claude Code',      file: 'CLAUDE.md',                        hasAgents: true,  hasSkills: true  },
+  cursor:   { label: 'Cursor',           file: '.cursorrules',                     hasAgents: false, hasSkills: false },
+  windsurf: { label: 'Windsurf',         file: '.windsurfrules',                   hasAgents: false, hasSkills: false },
+  copilot:  { label: 'GitHub Copilot',   file: '.github/copilot-instructions.md',  hasAgents: false, hasSkills: false },
+  codex:    { label: 'OpenAI Codex',     file: 'AGENTS.md',                        hasAgents: false, hasSkills: true  },
 };
 
 const TEMPLATE_MAP = {
@@ -28,6 +29,7 @@ const TEMPLATE_MAP = {
   cursor:   ['cursorrules.template',          'tool-append.template'],
   windsurf: ['windsurfrules.template',        'tool-append.template'],
   copilot:  ['copilot-instructions.template', 'tool-append.template'],
+  codex:    ['agents-md.template',            'tool-append.template'],
 };
 
 function ask(question) {
@@ -40,6 +42,20 @@ function ask(question) {
   });
 }
 
+function copySkillsDir(src, dest) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      if (!fs.existsSync(destPath)) fs.mkdirSync(destPath, { recursive: true });
+      copySkillsDir(srcPath, destPath);
+    } else if (!fs.existsSync(destPath)) {
+      fs.copyFileSync(srcPath, destPath);
+      console.log(`  create  ${path.relative(process.cwd(), destPath)}`);
+    }
+  }
+}
+
 function hasSyntropicMarker(filePath) {
   if (!fs.existsSync(filePath)) return false;
   return fs.readFileSync(filePath, 'utf8').includes('<!-- syntropic -->');
@@ -154,7 +170,7 @@ async function run(args) {
     writeOrAppend(fullTpl, appendTpl, destPath, replacements);
   }
 
-  // If adding Claude, also copy agents
+  // If adding Claude, copy agents + skills
   if (requestedTools.includes('claude')) {
     const claudeDir = path.join(targetDir, '.claude');
     const templateClaudeDir = path.join(TEMPLATES_DIR, '.claude');
@@ -183,10 +199,25 @@ async function run(args) {
           fs.copyFileSync(egSrc, egDest);
           console.log(`  create  ${path.relative(process.cwd(), egDest)}`);
         }
+        // Copy skills
+        const skillsSrc = path.join(templateClaudeDir, 'skills');
+        const skillsDest = path.join(claudeDir, 'skills');
+        if (fs.existsSync(skillsSrc)) {
+          copySkillsDir(skillsSrc, skillsDest);
+        }
       }
     }
   }
 
+  // If adding Codex, copy .agents/skills
+  if (requestedTools.includes('codex')) {
+    const agentsSrc = path.join(TEMPLATES_DIR, '.agents', 'skills');
+    const agentsDest = path.join(targetDir, '.agents', 'skills');
+    if (fs.existsSync(agentsSrc)) {
+      copySkillsDir(agentsSrc, agentsDest);
+    }
+  }
+
   console.log(`
   Done! Added: ${requestedTools.map(t => TOOLS[t].label).join(', ')}
 `);

package/commands/health.js

@@ -21,6 +21,7 @@ function run() {
     { name: 'Cursor',          path: '.cursorrules' },
     { name: 'Windsurf',        path: '.windsurfrules' },
     { name: 'GitHub Copilot',  path: path.join('.github', 'copilot-instructions.md') },
+    { name: 'OpenAI Codex',   path: 'AGENTS.md' },
   ];
 
   const foundTools = [];

package/commands/init.js

@@ -15,10 +15,11 @@ 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 },
+  claude:   { label: 'Claude Code',      file: 'CLAUDE.md',                        hasAgents: true,  hasSkills: true  },
+  cursor:   { label: 'Cursor',           file: '.cursorrules',                     hasAgents: false, hasSkills: false },
+  windsurf: { label: 'Windsurf',         file: '.windsurfrules',                   hasAgents: false, hasSkills: false },
+  copilot:  { label: 'GitHub Copilot',   file: '.github/copilot-instructions.md',  hasAgents: false, hasSkills: false },
+  codex:    { label: 'OpenAI Codex',     file: 'AGENTS.md',                        hasAgents: false, hasSkills: true  },
 };
 
 function ask(question) {
@@ -147,6 +148,9 @@ function detectTools(targetDir) {
   if (fs.existsSync(path.join(targetDir, '.github', 'copilot-instructions.md'))) {
     detected.push('copilot');
   }
+  if (fs.existsSync(path.join(targetDir, 'AGENTS.md')) || fs.existsSync(path.join(targetDir, '.agents'))) {
+    detected.push('codex');
+  }
   return detected;
 }
 
@@ -202,11 +206,14 @@ async function run(args) {
 
   console.log('\n  Scaffolding...\n');
 
-  // Always exclude CLAUDE.md from copyDir — we handle all instruction files via writeOrAppend
-  const exclude = ['CLAUDE.md'];
+  // Always exclude instruction files from copyDir — we handle them via writeOrAppend
+  const exclude = ['CLAUDE.md', 'AGENTS.md'];
   if (!selectedTools.includes('claude')) {
     exclude.push('.claude');
   }
+  if (!selectedTools.includes('codex')) {
+    exclude.push('.agents');
+  }
 
   // Copy shared template files (workflows, scripts, agents)
   copyDir(TEMPLATES_DIR, targetDir, exclude);
@@ -217,6 +224,7 @@ async function run(args) {
     cursor:   ['cursorrules.template',          'tool-append.template'],
     windsurf: ['windsurfrules.template',        'tool-append.template'],
     copilot:  ['copilot-instructions.template', 'tool-append.template'],
+    codex:    ['agents-md.template',            'tool-append.template'],
   };
 
   // Generate instruction files — create new or append to existing
@@ -240,13 +248,25 @@ async function run(args) {
     return `    ${pad}${info.label} instructions`;
   }).join('\n');
 
-  const hasAgents = selectedTools.includes('claude');
+  const hasClaude = selectedTools.includes('claude');
+  const hasCodex = selectedTools.includes('codex');
+  const hasSkills = hasClaude || hasCodex;
+
+  let extras = '';
+  if (hasClaude) {
+    extras += '\n    .claude/EVERGREEN_RULES.md          Full rule reference';
+    extras += '\n    .claude/commands/*.md               Generic agents (dev, qa, research, plan, devops, security)';
+    extras += '\n    .claude/skills/syntropic-pipeline/  Discoverable skill for Claude Code';
+  }
+  if (hasCodex) {
+    extras += '\n    .agents/skills/syntropic-pipeline/  Discoverable skill for Codex';
+  }
 
   console.log(`
   Done! Your project is set up with the Syntropic pipeline.
 
   What was created:
-${toolFiles}${hasAgents ? '\n    .claude/EVERGREEN_RULES.md          Full rule reference\n    .claude/commands/*.md               Generic agents (dev, qa, research, plan, devops, security)' : ''}
+${toolFiles}${extras}
     .github/workflows/                  Daily health check with auto-remediation
     scripts/health-check.js             Local health check script
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "syntropic",
-  "version": "0.4.0",
-  "description": "Philosophy-as-code development pipeline for Claude Code, Cursor, Windsurf, and GitHub Copilot.",
+  "version": "0.5.0",
+  "description": "Philosophy-as-code development pipeline for Claude Code, Cursor, Windsurf, GitHub Copilot, and OpenAI Codex.",
   "bin": {
     "syntropic": "./bin/syntropic.js"
   },
@@ -14,6 +14,9 @@
     "cursor",
     "windsurf",
     "github-copilot",
+    "openai-codex",
+    "agents-md",
+    "skill-md",
     "ai-development",
     "dev-pipeline",
     "syntropic"

package/templates/.agents/skills/syntropic-pipeline/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: syntropic-pipeline
+description: Use this skill when starting any non-trivial task. It enforces the Syntropic development methodology — a disciplined process that scales to the task size. Invoke before writing code.
+---
+
+# Syntropic Development Pipeline
+
+You follow a disciplined development process. Before writing any code, identify the cycle weight:
+
+- **Full Cycle** (>3 files or new patterns): Research → Plan → Implement → Review
+- **Lightweight Cycle** (1-3 files, known patterns): Plan → Implement → Review
+- **Minimum Cycle** (trivial/obvious): Implement → Verify
+
+**State the cycle before writing any code.** When in doubt, go one level UP.
+
+## Core Rules
+
+### Pre-Flight Loop
+BEFORE every deploy: build must pass, no localhost/127.0.0.1 references in source.
+AFTER every deploy: verify the live URL works.
+
+### Ship and Iterate
+Default: Build → Deploy → Show result.
+Only ask if: Destructive, Expensive, or Irreversible.
+
+### Hypothesis-Driven Debugging
+1. State hypothesis ("X because Y")
+2. Test WITHOUT code changes (logs, DB, API)
+3. Only code if confirmed
+4. 3rd attempt same issue → STOP, deep investigation
+
+### No Workarounds Without Approval
+Never implement bypass code, temporary hardcoded values, or "fix later" shortcuts without explicit approval.
+
+### Live Site Testing
+All new features go to the test page FIRST.
+DO NOT modify production without explicit approval.
+Workflow: Build on test → push → verify live → promote with approval.
+
+### Session Continuity
+On session reset: re-read project instructions, check git status, verify current state before proceeding.
+
+## Implementation Standards
+
+1. **Read before write** — always read existing code before modifying
+2. **Match existing patterns** — follow codebase conventions
+3. **Minimal changes** — only change what's needed
+4. **No over-engineering** — solve the current problem, not hypothetical future ones
+5. **Security first** — no injection vulnerabilities, no hardcoded secrets
+6. **Test what you build** — verify it works before marking done
+
+## Efficiency
+
+Before complex tasks: estimate cost vs. value.
+After cycles: note what worked and what was wasteful.
+Better output AND fewer resources. Never sacrifice quality to save tokens.

package/templates/.claude/skills/syntropic-pipeline/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: syntropic-pipeline
+description: Use this skill when starting any non-trivial task. It enforces the Syntropic development methodology — a disciplined process that scales to the task size. Invoke before writing code.
+---
+
+# Syntropic Development Pipeline
+
+You follow a disciplined development process. Before writing any code, identify the cycle weight:
+
+- **Full Cycle** (>3 files or new patterns): `/research` → `/plan` → `/dev` → `/qa`
+- **Lightweight Cycle** (1-3 files, known patterns): `/plan` → `/dev` → `/qa`
+- **Minimum Cycle** (trivial/obvious): `/dev` → verify
+
+**State the cycle before writing any code.** When in doubt, go one level UP.
+
+## Core Rules
+
+### EG1: Pre-Flight Loop
+BEFORE every deploy: build must pass (`npm run build` or equivalent), no localhost/127.0.0.1 references in source.
+AFTER every deploy: verify the live URL works.
+
+### EG2: Ship and Iterate
+Default: Build → Deploy → Show result.
+Only ask if: Destructive, Expensive, or Irreversible.
+
+### EG3: Hypothesis-Driven Debugging
+1. State hypothesis ("X because Y")
+2. Test WITHOUT code changes (logs, DB, API)
+3. Only code if confirmed
+4. 3rd attempt same issue → STOP, deep investigation
+
+### EG5: No Workarounds Without Approval
+Never implement bypass code, temporary hardcoded values, or "fix later" shortcuts without explicit approval.
+
+### EG8: Live Site Testing
+All new features go to the test page FIRST.
+DO NOT modify production without explicit approval.
+Workflow: Build on test → push → verify live → promote with approval.
+
+### EG9: Session Continuity
+On session reset: re-read project instructions, check git status, verify current state before proceeding.
+
+## Implementation Standards
+
+1. **Read before write** — always read existing code before modifying
+2. **Match existing patterns** — follow codebase conventions
+3. **Minimal changes** — only change what's needed
+4. **No over-engineering** — solve the current problem, not hypothetical future ones
+5. **Security first** — no injection vulnerabilities, no hardcoded secrets
+6. **Test what you build** — verify it works before marking done
+
+## Efficiency (PRISM Methodology)
+
+Before complex tasks: estimate cost vs. value.
+After cycles: note what worked and what was wasteful.
+Better output AND fewer resources. Never sacrifice quality to save tokens.

package/templates/agents-md.template

@@ -0,0 +1,84 @@
+<!-- syntropic -->
+# AGENTS.md — {{PROJECT_NAME}}
+
+**This file is loaded automatically by Codex. Follow these rules for all work in this project.**
+
+---
+
+## MANDATORY: Implementation Pipeline
+
+Before starting ANY task, identify the cycle weight:
+
+- **Full Cycle** (>3 files or new patterns): Research → Plan → Implement → Review
+- **Lightweight Cycle** (1-3 files, known patterns): Plan → Implement → Review
+- **Minimum Cycle** (trivial/obvious): Implement → Verify
+
+State the cycle before writing any code. When in doubt, go one level UP.
+
+---
+
+## Core Rules
+
+### Pre-Flight Loop
+**BEFORE** every deploy:
+- Build must pass (`npm run build` or equivalent)
+- No localhost/127.0.0.1 references in source
+**AFTER** every deploy: verify the live URL works.
+
+### Ship and Iterate
+Default: Build → Deploy → Show result.
+Only ask if: Destructive, Expensive, or Irreversible.
+
+### Hypothesis-Driven Debugging
+1. State hypothesis ("X because Y")
+2. Test WITHOUT code changes (logs, DB, API)
+3. Only code if confirmed
+4. 3rd attempt same issue → STOP, deep investigation
+
+### No Workarounds Without Approval
+Never implement bypass code, temporary hardcoded values, or "fix later" shortcuts without explicit approval.
+
+### Live Site Testing
+- Test page: {{TEST_URL}} — all new features go here FIRST
+- Production: {{PROD_URL}} — DO NOT modify without explicit approval
+- Workflow: Build on test → push → verify live → promote with approval
+
+### Session Continuity
+On session reset: re-read this file, check git status, verify current state before proceeding.
+
+---
+
+## Project: {{PROJECT_NAME}}
+
+**Production domain:** {{PROD_DOMAIN}}
+**Test page:** {{TEST_URL}}
+**Production page:** {{PROD_URL}}
+
+---
+
+## Efficiency
+
+- **Before complex tasks**: estimate cost vs. value
+- **After cycles**: note what worked and what was wasteful
+- Better output AND fewer resources. Never sacrifice quality to save tokens.
+
+---
+
+## Implementation Standards
+
+1. **Read before write** — always read existing code before modifying
+2. **Match existing patterns** — follow codebase conventions
+3. **Minimal changes** — only change what's needed
+4. **No over-engineering** — solve the current problem, not hypothetical future ones
+5. **Security first** — no injection vulnerabilities, no hardcoded secrets
+6. **Test what you build** — verify it works before marking done
+
+---
+
+## Communication
+
+- Be direct and concise
+- Recommend the objectively best solution
+- If you made a mistake, own it directly
+
+<!-- Generated by syntropic — development methodology for AI coding tools (https://npmjs.com/package/syntropic) -->