Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
feat(tools): add loop-sync CLI for drift detection and configuration sync
qiyuanjiang8361f55d07c1
diff --git a/tools/loop-sync/README.md b/tools/loop-sync/README.mdnew file mode 100644index 0000000..1794137--- /dev/null+++ b/tools/loop-sync/README.md@@ -0,0 +1,115 @@+# loop-sync++Detect and sync drift between Loop configuration files in your repository.++## Why loop-sync?++When working in teams, Loop configurations can drift over time:++- STATE.md and LOOP.md get out of sync+- Skills are updated but not reflected in configuration+- Required files are missing+- Configuration drifts from starters++`loop-sync` detects these issues and provides actionable suggestions.++## Installation++```bash+npm install -g @cobusgreyling/loop-sync+# or+npx @cobusgreyling/loop-sync .+```++## Usage++```bash+loop-sync [target-dir] [options]+```++### Options++| Option | Description |+|--------|-------------|+| `-a, --auto-fix` | Attempt to auto-fix issues (experimental) |+| `-d, --dry-run` | Show what would be done without making changes |+| `-v, --verbose` | Show detailed information |+| `--json` | Output JSON format |+| `-h, --help` | Show help |++### Examples++```bash+# Basic sync check+loop-sync .++# Verbose output+loop-sync ./my-project -v++# JSON output for scripting+loop-sync ./my-project --json+```++## What it checks++1. **Required files**+ - STATE.md (required)+ - LOOP.md (required)+ - AGENTS.md (recommended)++2. **STATE.md ↔ LOOP.md consistency**+ - Structural similarity+ - State file references+ - Pattern consistency++3. **Skills directory**+ - Existence of `.claude/skills/`+ - Version information in SKILL.md files++4. **Configuration drift**+ - Missing references+ - Orphaned files+ - Inconsistencies++## Score Interpretation++| Score | Level | Meaning |+|-------|-------|---------|+| 90-100 | Healthy | No issues detected |+| 70-89 | Warning | Minor inconsistencies |+| 0-69 | Critical | Major issues need attention |++## Output Example++```+Loop Sync Report+══════════════════════════════════════════════════+Score: 85/100 (healthy)++✅ No issues detected. Configuration is consistent.++💡 Suggestions:+ - Run loop-init to scaffold missing files+```++## Integration with CI/CD++Add to your GitHub Actions workflow:++```yaml+- name: Run loop-sync+ run: npx @cobusgreyling/loop-sync .+```++## Development++```bash+cd tools/loop-sync+npm install+npm run build+npm test+```++## License++MIT\ No newline at end of filediff --git a/tools/loop-sync/package.json b/tools/loop-sync/package.jsonnew file mode 100644index 0000000..73584bc--- /dev/null+++ b/tools/loop-sync/package.json@@ -0,0 +1,39 @@+{+ "name": "@cobusgreyling/loop-sync",+ "version": "1.0.0",+ "description": "Detect and sync drift between Loop configuration files (STATE.md ↔ LOOP.md, Skills versions)",+ "type": "module",+ "main": "dist/cli.js",+ "bin": {+ "loop-sync": "./dist/cli.js"+ },+ "files": [+ "dist",+ "README.md"+ ],+ "scripts": {+ "build": "tsc",+ "test": "node test/sync.test.mjs",+ "bundle": "node scripts/bundle-assets.mjs"+ },+ "keywords": [+ "loop-engineering",+ "sync",+ "drift-detection",+ "configuration"+ ],+ "author": "Cobus Greyling",+ "license": "MIT",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/cobusgreyling/loop-engineering.git",+ "directory": "tools/loop-sync"+ },+ "homepage": "https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-sync#readme",+ "bugs": {+ "url": "https://github.com/cobusgreyling/loop-engineering/issues"+ },+ "devDependencies": {+ "typescript": "^5.9.3"+ }+}\ No newline at end of filediff --git a/tools/loop-sync/src/cli.ts b/tools/loop-sync/src/cli.tsnew file mode 100644index 0000000..ee19f77--- /dev/null+++ b/tools/loop-sync/src/cli.ts@@ -0,0 +1,89 @@+#!/usr/bin/env node+/**+ * Loop Sync CLI+ *+ * Detect and sync drift between Loop configuration files+ */++import { runSync, formatReport, type SyncOptions, type DriftReport } from './sync.js';++function parseArgs(argv: string[]): SyncOptions {+ let targetDir = '.';+ let autoFix = false;+ let dryRun = false;+ let verbose = false;+ let json = false;+ let help = false;++ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--help' || a === '-h') help = true;+ else if (a === '--auto-fix' || a === '-a') autoFix = true;+ else if (a === '--dry-run' || a === '-d') dryRun = true;+ else if (a === '--verbose' || a === '-v') verbose = true;+ else if (a === '--json') json = true;+ else if (!a.startsWith('-')) targetDir = a;+ }++ return { targetDir, autoFix, dryRun, verbose, help };+}++async function main() {+ const args = parseArgs(process.argv.slice(2));++ if (args.help) {+ console.log(`loop-sync — detect and sync drift between Loop configuration files++Usage:+ loop-sync [target-dir] [options]++Options:+ -a, --auto-fix Attempt to auto-fix issues (experimental)+ -d, --dry-run Show what would be done without making changes+ -v, --verbose Show detailed information+ --json Output JSON format+ -h, --help Show this help++Examples:+ loop-sync .+ loop-sync ./my-project -v+ loop-sync ./my-project --json++The tool checks:+ - STATE.md ↔ LOOP.md consistency+ - Required files (STATE.md, LOOP.md, AGENTS.md)+ - Skills directory structure+ - Configuration drift indicators++Score interpretation:+ - 90-100: Healthy (no issues)+ - 70-89: Warning (minor inconsistencies)+ - 0-69: Critical (major issues need attention)++Docs: https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-sync+`);+ process.exit(0);+ }++ try {+ const report = await runSync(args);++ if (args.json) {+ console.log(JSON.stringify(report, null, 2));+ } else {+ console.log(formatReport(report));+ }++ // Exit with appropriate code+ if (report.level === 'critical') {+ process.exit(1);+ } else if (report.level === 'warning') {+ process.exit(2);+ }+ } catch (error) {+ console.error('loop-sync failed:', error instanceof Error ? error.message : error);+ process.exit(1);+ }+}++main();\ No newline at end of filediff --git a/tools/loop-sync/src/sync.ts b/tools/loop-sync/src/sync.tsnew file mode 100644index 0000000..e95242e--- /dev/null+++ b/tools/loop-sync/src/sync.ts@@ -0,0 +1,372 @@+/**+ * Loop Sync - Detect and sync drift between Loop configuration files+ *+ * This module detects:+ * 1. STATE.md ↔ LOOP.md consistency+ * 2. Skills version updates+ * 3. Missing required files+ * 4. Configuration drift from starters+ */++import { readFile, writeFile, access, mkdir } from 'node:fs/promises';+import { readdir, stat } from 'node:fs/promises';+import path from 'node:path';++export interface DriftReport {+ score: number; // 0-100 consistency score+ level: 'healthy' | 'warning' | 'critical';+ issues: DriftIssue[];+ suggestions: string[];+ timestamp: string;+}++export interface DriftIssue {+ type: 'missing' | 'outdated' | 'inconsistent' | 'orphaned';+ file: string;+ message: string;+ severity: 'error' | 'warning' | 'info';+ suggestion?: string;+}++export interface SyncOptions {+ targetDir: string;+ autoFix: boolean;+ dryRun: boolean;+ verbose: boolean;+}++/**+ * Check if a file exists+ */+async function fileExists(filePath: string): Promise<boolean> {+ try {+ await access(filePath);+ return true;+ } catch {+ return false;+ }+}++/**+ * Read file content+ */+async function readFileContent(filePath: string): Promise<string | null> {+ try {+ return await readFile(filePath, 'utf8');+ } catch {+ return null;+ }+}++/**+ * Extract frontmatter from markdown files+ */+function extractFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {+ const frontmatter: Record<string, string> = {};+ let body = content;++ if (content.startsWith('---')) {+ const endIndex = content.indexOf('---', 3);+ if (endIndex !== -1) {+ const fmContent = content.slice(3, endIndex);+ body = content.slice(endIndex + 3);++ for (const line of fmContent.split('\n')) {+ const colonIndex = line.indexOf(':');+ if (colonIndex !== -1) {+ const key = line.slice(0, colonIndex).trim();+ const value = line.slice(colonIndex + 1).trim();+ frontmatter[key] = value;+ }+ }+ }+ }++ return { frontmatter, body };+}++/**+ * Extract patterns from LOOP.md+ */+function extractLoopPatterns(loopContent: string): string[] {+ const patterns: string[] = [];++ // Look for pattern references+ const patternRegex = /pattern[s]?[\s]*[:=][\s]*([\w\-]+)/gi;+ let match;+ while ((match = patternRegex.exec(loopContent)) !== null) {+ patterns.push(match[1]);+ }++ return patterns;+}++/**+ * Extract state file references from LOOP.md+ */+function extractStateFiles(loopContent: string): string[] {+ const stateFiles: string[] = [];++ // Look for STATE.md or other state file references+ const stateRegex = /(?:state[s]?[\s]*[:=][\s]*|update[\s]+)([\w\-]+\.md)/gi;+ let match;+ while ((match = stateRegex.exec(loopContent)) !== null) {+ stateFiles.push(match[1]);+ }++ return stateFiles;+}++/**+ * Compare two markdown files for consistency+ */+function compareMarkdownFiles(+ file1Content: string,+ file2Content: string,+ threshold: number = 0.5+): { similarity: number; differences: string[] } {+ const differences: string[] = [];++ // Extract headings from both files+ const headings1 = file1Content.match(/^## .+$/gm) || [];+ const headings2 = file2Content.match(/^## .+$/gm) || [];++ // Check heading consistency+ const headingSet1 = new Set(headings1.map(h => h.toLowerCase()));+ const headingSet2 = new Set(headings2.map(h => h.toLowerCase()));++ const allHeadings = new Set([...headingSet1, ...headingSet2]);+ let matchingHeadings = 0;++ for (const heading of allHeadings) {+ if (headingSet1.has(heading) && headingSet2.has(heading)) {+ matchingHeadings++;+ } else if (!headingSet1.has(heading)) {+ differences.push(`Missing heading in file 1: ${heading}`);+ } else {+ differences.push(`Missing heading in file 2: ${heading}`);+ }+ }++ const similarity = allHeadings.size === 0 ? 1 : matchingHeadings / allHeadings.size;++ return { similarity, differences };+}++/**+ * Scan skills directory for version information+ */+async function scanSkillsDirectory(targetDir: string): Promise<Map<string, string>> {+ const skillsVersions = new Map<string, string>();+ const skillsDir = path.join(targetDir, '.claude', 'skills');++ if (!await fileExists(skillsDir)) {+ return skillsVersions;+ }++ try {+ const entries = await readdir(skillsDir);+ for (const entry of entries) {+ const skillPath = path.join(skillsDir, entry);+ const statResult = await stat(skillPath);++ if (statResult.isDirectory()) {+ const skillMd = path.join(skillPath, 'SKILL.md');+ const content = await readFileContent(skillMd);++ if (content) {+ const { frontmatter } = extractFrontmatter(content);+ skillsVersions.set(entry, frontmatter.version || 'unknown');+ }+ }+ }+ } catch (error) {+ // Ignore errors+ }++ return skillsVersions;+}++/**+ * Main sync function+ */+export async function runSync(options: SyncOptions): Promise<DriftReport> {+ const { targetDir, autoFix, dryRun, verbose } = options;+ const issues: DriftIssue[] = [];+ const suggestions: string[] = [];++ // Define required files+ const requiredFiles = [+ 'STATE.md',+ 'LOOP.md',+ 'AGENTS.md',+ ];++ // Check for missing required files+ for (const file of requiredFiles) {+ const filePath = path.join(targetDir, file);+ if (!await fileExists(filePath)) {+ issues.push({+ type: 'missing',+ file,+ message: `${file} is missing`,+ severity: 'error',+ suggestion: `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,+ });+ }+ }++ // Check STATE.md ↔ LOOP.md consistency+ const statePath = path.join(targetDir, 'STATE.md');+ const loopPath = path.join(targetDir, 'LOOP.md');++ if (await fileExists(statePath) && await fileExists(loopPath)) {+ const stateContent = await readFileContent(statePath);+ const loopContent = await readFileContent(loopPath);++ if (stateContent && loopContent) {+ // Extract patterns from LOOP.md+ const patterns = extractLoopPatterns(loopContent);++ // Extract state files from LOOP.md+ const stateFiles = extractStateFiles(loopContent);++ // Check if STATE.md is referenced in LOOP.md+ if (!stateFiles.includes('STATE.md')) {+ issues.push({+ type: 'inconsistent',+ file: 'LOOP.md',+ message: 'LOOP.md does not reference STATE.md',+ severity: 'warning',+ suggestion: 'Add STATE.md to the state files list in LOOP.md',+ });+ }++ // Compare structural similarity+ const { similarity, differences } = compareMarkdownFiles(stateContent, loopContent, 0.5);++ if (similarity < 0.3 && differences.length > 0) {+ issues.push({+ type: 'inconsistent',+ file: 'STATE.md ↔ LOOP.md',+ message: 'Low structural similarity between STATE.md and LOOP.md',+ severity: 'warning',+ suggestion: 'Review both files for consistency',+ });++ if (verbose) {+ for (const diff of differences.slice(0, 3)) {+ issues.push({+ type: 'inconsistent',+ file: 'STATE.md ↔ LOOP.md',+ message: diff,+ severity: 'info',+ });+ }+ }+ }+ }+ }++ // Scan skills for version information+ const skillsVersions = await scanSkillsDirectory(targetDir);++ if (skillsVersions.size === 0 && await fileExists(path.join(targetDir, '.claude', 'skills'))) {+ suggestions.push('No skills found. Run loop-init to scaffold skills.');+ }++ // Calculate score+ let score = 100;+ for (const issue of issues) {+ if (issue.severity === 'error') {+ score -= 20;+ } else if (issue.severity === 'warning') {+ score -= 10;+ } else {+ score -= 1;+ }+ }+ score = Math.max(0, Math.min(100, score));++ // Determine level+ let level: 'healthy' | 'warning' | 'critical' = 'healthy';+ if (score < 40) {+ level = 'critical';+ } else if (score < 70) {+ level = 'warning';+ }++ // Add suggestions based on issues+ if (issues.some(i => i.type === 'missing')) {+ suggestions.push('Run loop-init to scaffold missing files');+ }++ if (issues.some(i => i.type === 'inconsistent')) {+ suggestions.push('Review STATE.md and LOOP.md for consistency');+ }++ return {+ score,+ level,+ issues,+ suggestions,+ timestamp: new Date().toISOString(),+ };+}++/**+ * Format report for CLI output+ */+export function formatReport(report: DriftReport): string {+ const lines: string[] = [];++ lines.push('');+ lines.push('Loop Sync Report');+ lines.push('══════════════════════════════════════════════════');+ lines.push(`Score: ${report.score}/100 (${report.level})`);+ lines.push('');++ if (report.issues.length === 0) {+ lines.push('✅ No issues detected. Configuration is consistent.');+ } else {+ lines.push(`Found ${report.issues.length} issue(s):`);+ lines.push('');++ const errors = report.issues.filter(i => i.severity === 'error');+ const warnings = report.issues.filter(i => i.severity === 'warning');+ const infos = report.issues.filter(i => i.severity === 'info');++ if (errors.length > 0) {+ lines.push('❌ Errors:');+ for (const issue of errors) {+ lines.push(` - ${issue.file}: ${issue.message}`);+ }+ lines.push('');+ }++ if (warnings.length > 0) {+ lines.push('⚠️ Warnings:');+ for (const issue of warnings) {+ lines.push(` - ${issue.file}: ${issue.message}`);+ }+ lines.push('');+ }++ if (infos.length > 0) {+ lines.push('ℹ️ Information:');+ for (const issue of infos) {+ lines.push(` - ${issue.file}: ${issue.message}`);+ }+ lines.push('');+ }+ }++ if (report.suggestions.length > 0) {+ lines.push('💡 Suggestions:');+ for (const suggestion of report.suggestions) {+ lines.push(` - ${suggestion}`);+ }+ }++ return lines.join('\n');+}\ No newline at end of filediff --git a/tools/loop-sync/test/sync.test.mjs b/tools/loop-sync/test/sync.test.mjsnew file mode 100644index 0000000..f5c4f8e--- /dev/null+++ b/tools/loop-sync/test/sync.test.mjs@@ -0,0 +1,128 @@+import { describe, it, expect } from 'node:test';+import assert from 'node:assert/strict';+import path from 'node:path';+import { mkdir, writeFile, rm } from 'node:fs/promises';+import { runSync, formatReport } from '../src/sync.js';++// Create a temporary test directory+const testDir = path.join(process.cwd(), '.test-tmp');++async function setupTestDir() {+ await mkdir(testDir, { recursive: true });++ // Create STATE.md+ await writeFile(+ path.join(testDir, 'STATE.md'),+ `# Loop State++Last run: 2026-06-22++## High Priority+- No items++## Watch List+- No items+`+ );++ // Create LOOP.md+ await writeFile(+ path.join(testDir, 'LOOP.md'),+ `# Loop Configuration++## Patterns+- daily-triage++## State Files+- STATE.md++## Schedule+- Cadence: 1d+- Level: L1+`+ );+}++async function cleanupTestDir() {+ await rm(testDir, { recursive: true, force: true });+}++describe('runSync', () => {+ beforeEach(setupTestDir);+ afterEach(cleanupTestDir);++ it('should return a valid DriftReport', async () => {+ const report = await runSync({ targetDir: testDir });++ assert.ok(typeof report.score === 'number');+ assert.ok(['healthy', 'warning', 'critical'].includes(report.level));+ assert.ok(Array.isArray(report.issues));+ assert.ok(Array.isArray(report.suggestions));+ assert.ok(report.timestamp);+ });++ it('should detect missing files', async () => {+ // Remove AGENTS.md (it's not created by setup)+ const report = await runSync({ targetDir: testDir });++ // Should have at least one issue about missing AGENTS.md+ const agentsIssue = report.issues.find(i => i.file === 'AGENTS.md');+ assert.ok(agentsIssue);+ assert.ok(agentsIssue.message.includes('missing'));+ });++ it('should calculate score correctly', async () => {+ const report = await runSync({ targetDir: testDir });++ // With STATE.md and LOOP.md present, score should be reasonable+ assert.ok(report.score >= 0);+ assert.ok(report.score <= 100);+ });++ it('should provide suggestions', async () => {+ const report = await runSync({ targetDir: testDir });++ // Should have at least one suggestion+ assert.ok(report.suggestions.length > 0);+ });+});++describe('formatReport', () => {+ it('should format report as string', () => {+ const report = {+ score: 85,+ level: 'healthy',+ issues: [],+ suggestions: ['Run loop-init'],+ timestamp: new Date().toISOString(),+ };++ const formatted = formatReport(report);++ assert.ok(typeof formatted === 'string');+ assert.ok(formatted.includes('Loop Sync Report'));+ assert.ok(formatted.includes('85/100'));+ });++ it('should show issues when present', () => {+ const report = {+ score: 60,+ level: 'warning',+ issues: [+ {+ type: 'missing',+ file: 'AGENTS.md',+ message: 'AGENTS.md is missing',+ severity: 'error',+ },+ ],+ suggestions: [],+ timestamp: new Date().toISOString(),+ };++ const formatted = formatReport(report);++ assert.ok(formatted.includes('AGENTS.md'));+ assert.ok(formatted.includes('missing'));+ });+});\ No newline at end of filediff --git a/tools/loop-sync/tsconfig.json b/tools/loop-sync/tsconfig.jsonnew file mode 100644index 0000000..8e6e0b2--- /dev/null+++ b/tools/loop-sync/tsconfig.json@@ -0,0 +1,15 @@+{+ "compilerOptions": {+ "target": "ES2022",+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "outDir": "./dist",+ "rootDir": "./src",+ "strict": true,+ "esModuleInterop": true,+ "skipLibCheck": true,+ "declaration": true+ },+ "include": ["src/**/*"],+ "exclude": ["node_modules", "dist", "test"]+}\ No newline at end of file