syntropic 0.8.1 → 0.9.0

package/README.md

@@ -1,127 +1,112 @@
 # syntropic
 
-A development methodology for AI-assisted coding. Works with **Claude Code**, **Cursor**, **Windsurf**, **GitHub Copilot**, and **OpenAI Codex**.
+**Ship better software. Prove it on your own code first.**
 
-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.
+A development methodology for AI-assisted coding. Works with **Claude Code**, **Cursor**, **Windsurf**, **GitHub Copilot**, and **OpenAI Codex**.
 
-## Quick Start
+## Try Before You Install
 
 ```bash
-npx syntropic init my-project
+npx syntropic audit
 ```
 
-Or add to an existing project:
+Analyses your last 20 git commits for process issues — localhost references, env files in git, commit discipline, fix ratios, governance docs. No install needed. Nothing sent anywhere. See what the methodology catches on **your** code.
+
+## Install
 
 ```bash
-cd my-project
 npx syntropic init
 ```
 
-You'll be asked which AI tools you use. The CLI generates a minimal instruction file for each:
-
-| Tool | File Generated |
-|------|---------------|
-| Claude Code | `CLAUDE.md` |
-| Cursor | `.cursorrules` |
-| Windsurf | `.windsurfrules` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| OpenAI Codex | `AGENTS.md` |
-
-## How It Works
-
-**Server-served, client-computed.** Your instruction file contains a single bootstrap rule (EG13) that tells your AI tool to fetch the full methodology from the Syntropic server at the start of every development cycle. All rules, agents, and learning data are served fresh — always up to date, zero local files to maintain.
-
-Your LLM does all the compute. Syntropic serves the methodology but runs zero inference. Your data stays on your machine.
+You get: a disciplined development pipeline, governance doc templates, and a connection to the PRISM methodology network — so your rules stay current as the methodology evolves.
 
 ## What You Get
 
-**Evergreen Rules (EG1-EG13)** — fetched at runtime from the PRISM network:
+**Evergreen Rules** — battle-tested development rules fetched fresh at every cycle:
 
-- **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
-- **EG13: PRISM Sync** — fetch methodology at cycle start, report at cycle end
+| Rule | What it prevents | Real-world save |
+|------|-----------------|-----------------|
+| **EG1: Pre-flight** | Localhost refs, broken builds reaching production | Caught 3 localhost references pre-deploy |
+| **EG7: Pipeline** | AI jumping to code without research or planning | Structured 123 features across Full/Lightweight/Minimum cycles |
+| **EG8: Test first** | Untested changes reaching production users | Every fix caught on test page — 12 verified promotions |
+| **EG10: Env hygiene** | Env var corruption (trailing newlines, wrong formats) | Prevented silent API failures across 6 providers |
+| **EG11: Prod sync** | Access control divergence between test and production | Caught lockout bug before 8+ users were affected |
+| **EG14: Doc discipline** | Lost decisions, repeated mistakes, no project memory | Backlog, issues, and ADRs updated every cycle |
 
-**Generic Agents** (Claude Code, Codex) — dev, qa, research, plan, devops, security — served from the PRISM network, never cached to disk
+**Governance Docs** — project management templates your AI assistant reads before every cycle:
 
-**Health Check** — daily GitHub Action with auto-remediation (npm audit fix PRs)
+```
+.claude/docs/NORTH_STAR.md     Your vision, goals, and design principles
+.claude/docs/BACKLOG.md        Prioritised work with status tracking
+.claude/docs/ISSUES.md         Bug log and iteration tracker
+.claude/docs/adr/              Architectural Decision Records
+```
 
-**PRISM Network** — anonymous networked learning. Your AI tool fetches the latest methodology intelligence at cycle start, and optionally reports anonymous structural metadata at cycle end. Every user's cycles improve the methodology for everyone. Zero inference cost — your LLM does all compute.
+**Pipeline Agents** — research, dev, plan, qa, devops, security — fetched from the PRISM network so they're always up to date.
 
-## Commands
+**Health Check** — daily GitHub Action with auto-remediation (npm audit fix PRs).
 
-```bash
-# Scaffold a new project
-npx syntropic init my-project
+## Track Record
 
-# Select specific tools
-npx syntropic init my-project --tools claude,cursor
+Built in production on a real product (27 AI agents, 8-lens analyser, CLI, 7 free tools) over 10 weeks:
 
-# Customise project URLs (optional — sensible defaults applied)
-npx syntropic init my-project --name "My App" --domain myapp.com --test-url /staging --prod-url /
+- **123 features shipped**, each through a structured pipeline
+- **12 test→production promotions** — every feature verified on test page first
+- **3 bug classes prevented** by specific EG rules before reaching users
+- **0 undetected production incidents** after methodology adoption
 
-# Add a tool to an existing project
-npx syntropic add cursor
-npx syntropic add windsurf copilot
+## Trust & Privacy
 
-# Run a local health check (EG1 pre-flight)
-npx syntropic health
+**Everything is local.** Your `.claude/` directory — rules, agents, governance docs — lives in your repo. It's yours.
 
-# Manage anonymous telemetry (opt-out, default on)
-npx syntropic telemetry status
-npx syntropic telemetry disable
-npx syntropic telemetry enable
+**Telemetry is optional.** PRISM collects anonymous structural metadata (cycle weight, file count, framework — never code, names, or content). Double-hashed before transmission. Default: on. Opt out anytime:
 
-# Submit a PRISM cycle report (CLI handles hashing + signing)
-npx syntropic report --weight lightweight --phases research,plan,dev,qa,test --success true --iterations 1
+```bash
+syntropic telemetry disable
 ```
 
-## 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.
+**What's collected:** cycle weight, phases, success/failure, tool, OS, project shape.
+**Never collected:** file contents, names, code, diffs, commits, identity, API keys.
 
-## The Methodology
+**Clean exit.** Remove everything syntropic added (preserves your governance docs):
 
-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:
+```bash
+syntropic remove
+```
 
-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
+**Inspect the output.** Run `npm pack` on the package — everything that ships is plain text templates. The methodology is served from a public API endpoint you can curl yourself.
 
-Scale the process to the task. A typo fix doesn't need research. A new feature does.
+## Commands
 
-## Privacy
+```bash
+syntropic audit                    # Analyse git history (no install needed)
+syntropic init [project-name]      # Install methodology + docs
+syntropic add cursor windsurf      # Add tools to existing project
+syntropic remove                   # Clean uninstall (preserves docs)
+syntropic health                   # Run pre-flight checks
+syntropic report                   # Submit anonymous cycle report
+syntropic telemetry status         # Check telemetry setting
+syntropic analyse                  # Deep-dive analysis (8 philosophy lenses)
+```
 
-Syntropic collects pseudonymised usage patterns to improve the methodology for everyone. **Default: on (opt-out).**
+## How It Works
 
-**What is collected:** cycle weight, phases run, success/failure, iteration count, tool, OS, Node.js major version, project shape (has TypeScript/CI/tests, framework, file change bucket).
+Your instruction file contains a bootstrap rule (EG13) that fetches the full methodology from the PRISM network at cycle start. Rules, agents, and patterns are served fresh — always current, zero maintenance. Your LLM does all compute. Syntropic serves the methodology but runs zero inference.
 
-**What is NEVER collected:** file contents, file names, project names, code, diffs, commit messages, user identity, email, API keys.
+The governance docs give your AI assistant project memory — it checks priorities before coding and logs issues after. Over time, your docs become a structured record of every decision, bug, and iteration.
 
-**Pseudonymisation:** A random device ID is generated locally at install time. Before transmission, it is hashed client-side with a daily-rotating salt (`SHA-256(device_id + date)`), then hashed again server-side with a separate salt (`SHA-256(client_hash + server_salt)`). Neither the client hash nor the original device ID is stored server-side — only the double-hashed value, which cannot be reversed to identify a device or user. Inspired by [TelemetryDeck's MIT-licensed approach](https://telemetrydeck.com/docs/articles/anonymization-how-it-works/). GDPR-compliant by design.
+## Existing Projects
 
-Opt out anytime: `npx syntropic telemetry disable`
+Running `syntropic init` in a project that already has a `CLAUDE.md` or `.cursorrules` **appends** the methodology — never overwrites. A `<!-- syntropic -->` marker prevents duplicates.
 
-## Philosophy
+## Research
 
-- **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
+The methodology is grounded in published research: [zenodo.org/records/17894441](https://zenodo.org/records/17894441)
 
 ## Links
 
 - [Website](https://www.syntropicworks.com)
-- [GitHub](https://github.com/petercholford-ship-it/syntropic-cli)
-- [Research Paper](https://zenodo.org/records/17894441) — the underlying research behind the methodology
-- [Intelligent Analyser](https://www.syntropicworks.com/analyser) — deep-dive analysis through 8 philosophy lenses
+- [Intelligent Analyser](https://www.syntropicworks.com/analyser) — deep-dive product analysis through 8 philosophy lenses
 
 ## License
 

package/bin/syntropic.js

@@ -14,8 +14,10 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 const COMMANDS = {
+  audit: () => require('../commands/audit'),
   init: () => require('../commands/init'),
   add: () => require('../commands/add'),
+  remove: () => require('../commands/remove'),
   health: () => require('../commands/health'),
   telemetry: () => require('../commands/telemetry'),
   report: () => require('../commands/report'),
@@ -39,8 +41,10 @@ if (!command || args.includes('--help') || args.includes('-h')) {
   syntropic — Philosophy-as-code development pipeline
 
   Usage:
+    syntropic audit                 Analyse your git history for process issues (no install needed)
     syntropic init [project-name]   Scaffold a new project with the Syntropic pipeline
     syntropic add <tool> [tool...]  Add support for another AI tool
+    syntropic remove                Remove syntropic from this project (preserves your docs)
     syntropic analyse               Analyse your product using 8 philosophy lenses
     syntropic login                 Sign in to Syntropic (required for analyse)
     syntropic logout                Sign out

package/commands/audit.js

@@ -0,0 +1,293 @@
+/**
+ * syntropic audit [--commits <n>]
+ *
+ * Analyse your git history for development process issues.
+ * Proves value on your own code before installing anything.
+ * Pure local analysis — sends nothing, requires nothing.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = { commits: 20 };
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--help' || args[i] === '-h') { flags.help = true; continue; }
+    if (args[i].startsWith('--')) {
+      const key = args[i].replace('--', '');
+      flags[key] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+    }
+  }
+  return flags;
+}
+
+function git(cmd) {
+  try {
+    return execSync(`git ${cmd}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function colour(text, code) {
+  if (!process.stdout.isTTY) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+const green = (t) => colour(t, '32');
+const yellow = (t) => colour(t, '33');
+const red = (t) => colour(t, '31');
+const dim = (t) => colour(t, '2');
+const bold = (t) => colour(t, '1');
+
+function checkLocalhost(n) {
+  // Find commits that introduced localhost/127.0.0.1 references
+  const log = git(`log --oneline -${n} --format=%H`);
+  if (!log) return { issues: 0, detail: '' };
+
+  const hashes = log.split('\n').filter(Boolean);
+  let hits = 0;
+  const examples = [];
+
+  for (const hash of hashes) {
+    const diff = git(`diff ${hash}~1 ${hash} -- . ":(exclude)*.lock" ":(exclude)node_modules" 2>/dev/null`);
+    if (!diff) continue;
+
+    const addedLines = diff.split('\n').filter(l => l.startsWith('+') && !l.startsWith('+++'));
+    for (const line of addedLines) {
+      if (/localhost|127\.0\.0\.1/.test(line) && !/\/\/.*localhost/.test(line.replace(/https?:\/\/localhost/, 'MATCH'))) {
+        hits++;
+        if (examples.length < 2) {
+          const shortHash = hash.slice(0, 7);
+          const subject = git(`log --format=%s -1 ${hash}`);
+          examples.push(`${shortHash} ${subject}`);
+        }
+        break; // Count once per commit
+      }
+    }
+  }
+
+  return {
+    issues: hits,
+    detail: examples.length ? examples.map(e => `    ${dim(e)}`).join('\n') : '',
+  };
+}
+
+function checkEnvFiles(n) {
+  // Check if .env files are tracked in git
+  const tracked = git('ls-files').split('\n');
+  const envFiles = tracked.filter(f => {
+    const base = path.basename(f);
+    // .env.example, .env.sample, .env.template are fine
+    return /^\.env($|\.)/.test(base) && !/\.(example|sample|template)$/.test(base);
+  });
+  return {
+    issues: envFiles.length,
+    detail: envFiles.length ? envFiles.map(f => `    ${dim(f)}`).join('\n') : '',
+  };
+}
+
+function checkCommitConventions(n) {
+  const log = git(`log --oneline -${n} --no-merges --format=%s`);
+  if (!log) return { conventional: 0, total: 0, pct: 0 };
+
+  const subjects = log.split('\n').filter(Boolean);
+  const conventional = subjects.filter(s => /^(feat|fix|refactor|chore|docs|style|perf|test|ci|build|revert|sync|content|debug|security|spec)(\(.+\))?:/.test(s));
+
+  return {
+    conventional: conventional.length,
+    total: subjects.length,
+    pct: subjects.length > 0 ? Math.round(conventional.length / subjects.length * 100) : 0,
+  };
+}
+
+function checkFixRatio(n) {
+  const log = git(`log --oneline -${n} --no-merges --format=%s`);
+  if (!log) return { feats: 0, fixes: 0, ratio: 0, total: 0 };
+
+  const subjects = log.split('\n').filter(Boolean);
+  const feats = subjects.filter(s => /^feat(\(.+\))?:/.test(s)).length;
+  const fixes = subjects.filter(s => /^fix(\(.+\))?:/.test(s)).length;
+  const total = subjects.length;
+
+  return { feats, fixes, ratio: total > 0 ? Math.round(fixes / total * 100) : 0, total };
+}
+
+function checkFilesPerCommit(n) {
+  const log = git(`log --oneline -${n} --no-merges --format=%H`);
+  if (!log) return { avg: 0, max: 0 };
+
+  const hashes = log.split('\n').filter(Boolean);
+  const counts = hashes.map(h => {
+    const files = git(`diff --name-only ${h}~1 ${h} 2>/dev/null`);
+    return files ? files.split('\n').filter(Boolean).length : 0;
+  }).filter(c => c > 0);
+
+  if (counts.length === 0) return { avg: 0, max: 0 };
+
+  return {
+    avg: Math.round(counts.reduce((a, b) => a + b, 0) / counts.length * 10) / 10,
+    max: Math.max(...counts),
+  };
+}
+
+function checkGovernanceDocs() {
+  const cwd = process.cwd();
+  const docs = {
+    north_star: fs.existsSync(path.join(cwd, '.claude', 'docs', 'NORTH_STAR.md')) || fs.existsSync(path.join(cwd, '.claude', 'NORTH_STAR.md')),
+    backlog: fs.existsSync(path.join(cwd, '.claude', 'docs', 'BACKLOG.md')),
+    issues: fs.existsSync(path.join(cwd, '.claude', 'docs', 'ISSUES.md')),
+    adr: fs.existsSync(path.join(cwd, '.claude', 'docs', 'adr')),
+  };
+  const count = Object.values(docs).filter(Boolean).length;
+  return { count, total: 4, docs };
+}
+
+function computeScore(results) {
+  let score = 5; // Start at 5/10
+
+  // Localhost issues: -1 per issue, max -2
+  score -= Math.min(results.localhost.issues, 2);
+
+  // Env files tracked: -2 if any
+  if (results.envFiles.issues > 0) score -= 2;
+
+  // Conventional commits: +1 if >70%, +0.5 if >40%
+  if (results.conventions.pct >= 70) score += 1;
+  else if (results.conventions.pct >= 40) score += 0.5;
+
+  // Fix ratio: neutral if 30-50%, -0.5 if >60%
+  if (results.fixRatio.ratio > 60) score -= 0.5;
+
+  // Governance docs: +0.5 per doc present
+  score += results.governance.count * 0.5;
+
+  // Avg files per commit: -0.5 if >15 (giant commits)
+  if (results.filesPerCommit.avg > 15) score -= 0.5;
+
+  return Math.max(0, Math.min(10, Math.round(score * 2) / 2));
+}
+
+function run(args) {
+  const flags = parseFlags(args);
+
+  if (flags.help) {
+    console.log(`
+  syntropic audit — Analyse your git history for process issues
+
+  Usage:
+    syntropic audit [options]
+    npx syntropic audit              (no install needed)
+
+  Options:
+    --commits <n>   Number of recent commits to analyse (default: 20)
+
+  What it checks:
+    - Localhost/127.0.0.1 references committed to repo
+    - .env files tracked in git
+    - Commit message conventions
+    - Fix:feature ratio (iteration indicator)
+    - Average files per commit (scope discipline)
+    - Governance docs (North Star, Backlog, Issues, ADRs)
+
+  This is a local-only analysis. Nothing is sent anywhere.
+`);
+    return;
+  }
+
+  // Check we're in a git repo
+  const gitRoot = git('rev-parse --show-toplevel');
+  if (!gitRoot) {
+    console.error('\n  Not a git repository. Run this from a project with git history.\n');
+    process.exit(1);
+  }
+
+  const n = parseInt(flags.commits, 10) || DEFAULTS.commits;
+  const commitCount = git('rev-list --count HEAD');
+  const actualN = Math.min(n, parseInt(commitCount, 10) || n);
+
+  console.log(`\n  ${bold('syntropic audit')} — last ${actualN} commits\n`);
+
+  // Run all checks
+  const results = {
+    localhost: checkLocalhost(actualN),
+    envFiles: checkEnvFiles(actualN),
+    conventions: checkCommitConventions(actualN),
+    fixRatio: checkFixRatio(actualN),
+    filesPerCommit: checkFilesPerCommit(actualN),
+    governance: checkGovernanceDocs(),
+  };
+
+  const score = computeScore(results);
+
+  // Display results
+  const PAD = 24;
+
+  // EG1: Localhost
+  if (results.localhost.issues > 0) {
+    console.log(`  ${yellow('⚠')} ${'EG1  Pre-flight'.padEnd(PAD)} ${yellow(`${results.localhost.issues} commit${results.localhost.issues > 1 ? 's' : ''} contain localhost references`)}`);
+    if (results.localhost.detail) console.log(results.localhost.detail);
+  } else {
+    console.log(`  ${green('✓')} ${'EG1  Pre-flight'.padEnd(PAD)} ${green('No localhost references found')}`);
+  }
+
+  // EG10: Env files
+  if (results.envFiles.issues > 0) {
+    console.log(`  ${red('✗')} ${'EG10 Env hygiene'.padEnd(PAD)} ${red(`${results.envFiles.issues} .env file${results.envFiles.issues > 1 ? 's' : ''} tracked in git`)}`);
+    if (results.envFiles.detail) console.log(results.envFiles.detail);
+  } else {
+    console.log(`  ${green('✓')} ${'EG10 Env hygiene'.padEnd(PAD)} ${green('No .env files tracked')}`);
+  }
+
+  // Commit conventions
+  const convPct = results.conventions.pct;
+  const convIcon = convPct >= 70 ? green('✓') : convPct >= 40 ? yellow('⚠') : red('✗');
+  const convColour = convPct >= 70 ? green : convPct >= 40 ? yellow : red;
+  console.log(`  ${convIcon} ${'Commit discipline'.padEnd(PAD)} ${convColour(`${convPct}% conventional commits`)} ${dim(`(${results.conventions.conventional}/${results.conventions.total})`)}`);
+
+  // Fix ratio
+  const fixPct = results.fixRatio.ratio;
+  const fixIcon = fixPct <= 50 ? green('✓') : yellow('⚠');
+  const fixColour = fixPct <= 50 ? green : yellow;
+  console.log(`  ${fixIcon} ${'Fix ratio'.padEnd(PAD)} ${fixColour(`${fixPct}% of commits are fixes`)} ${dim(`(${results.fixRatio.fixes} fixes, ${results.fixRatio.feats} features)`)}`);
+
+  // Files per commit
+  const avgFiles = results.filesPerCommit.avg;
+  const filesIcon = avgFiles <= 10 ? green('✓') : avgFiles <= 15 ? yellow('⚠') : red('✗');
+  const filesColour = avgFiles <= 10 ? green : avgFiles <= 15 ? yellow : red;
+  console.log(`  ${filesIcon} ${'Scope discipline'.padEnd(PAD)} ${filesColour(`${avgFiles} avg files/commit`)} ${dim(`(max: ${results.filesPerCommit.max})`)}`);
+
+  // Governance docs
+  const govCount = results.governance.count;
+  const govIcon = govCount >= 3 ? green('✓') : govCount >= 1 ? yellow('⚠') : dim('○');
+  const govColour = govCount >= 3 ? green : govCount >= 1 ? yellow : dim;
+  const govNames = [];
+  if (results.governance.docs.north_star) govNames.push('North Star');
+  if (results.governance.docs.backlog) govNames.push('Backlog');
+  if (results.governance.docs.issues) govNames.push('Issues');
+  if (results.governance.docs.adr) govNames.push('ADRs');
+  console.log(`  ${govIcon} ${'Governance docs'.padEnd(PAD)} ${govColour(`${govCount}/4 present`)} ${dim(govNames.length ? `(${govNames.join(', ')})` : '(none)')}`);
+
+  // Score
+  console.log('');
+  const scoreColour = score >= 7 ? green : score >= 4 ? yellow : red;
+  console.log(`  ${bold('Score:')} ${scoreColour(`${score}/10`)}`);
+
+  // Recommendation
+  console.log('');
+  if (score >= 8) {
+    console.log(`  ${green('Strong development discipline.')} Syntropic can keep it that way.`);
+  } else if (score >= 5) {
+    console.log(`  ${yellow('Room for improvement.')} Common issues that a structured pipeline prevents.`);
+  } else {
+    console.log(`  ${red('Significant process gaps.')} A development methodology would catch these early.`);
+  }
+
+  console.log(`\n  ${dim('Run `syntropic init` to install the methodology and prevent these automatically.')}`);
+  console.log(`  ${dim('Learn more: https://www.syntropicworks.com')}\n`);
+}
+
+module.exports = run;

package/commands/init.js

@@ -186,6 +186,51 @@ function detectTools(targetDir) {
   return detected;
 }
 
+function scaffoldDocs(targetDir, projectName) {
+  const docsDir = path.join(targetDir, '.claude', 'docs');
+  const adrDir = path.join(docsDir, 'adr');
+  const docsTemplateDir = path.join(TEMPLATES_DIR, 'docs');
+
+  // Skip if docs dir already exists with content
+  if (fs.existsSync(docsDir)) {
+    const existing = fs.readdirSync(docsDir).filter(f => !f.startsWith('.'));
+    if (existing.length > 0) {
+      console.log(`  skip  .claude/docs/ (already exists with ${existing.length} items)`);
+      return;
+    }
+  }
+
+  if (!fs.existsSync(docsTemplateDir)) return;
+
+  fs.mkdirSync(adrDir, { recursive: true });
+
+  const today = new Date().toISOString().slice(0, 10);
+  const replacements = {
+    '\\{\\{PROJECT_NAME\\}\\}': projectName,
+    '\\{\\{CREATED_DATE\\}\\}': today,
+  };
+
+  // Copy doc templates, renaming .template to .md
+  const docFiles = [
+    { src: 'NORTH_STAR.template', dest: path.join(docsDir, 'NORTH_STAR.md') },
+    { src: 'BACKLOG.template', dest: path.join(docsDir, 'BACKLOG.md') },
+    { src: 'ISSUES.template', dest: path.join(docsDir, 'ISSUES.md') },
+    { src: path.join('adr', '000-TEMPLATE.template'), dest: path.join(adrDir, '000-TEMPLATE.md') },
+  ];
+
+  for (const { src, dest } of docFiles) {
+    const srcPath = path.join(docsTemplateDir, src);
+    if (!fs.existsSync(srcPath)) continue;
+
+    let content = fs.readFileSync(srcPath, 'utf8');
+    for (const [key, value] of Object.entries(replacements)) {
+      content = content.replace(new RegExp(key, 'g'), () => value);
+    }
+    fs.writeFileSync(dest, content, 'utf8');
+    console.log(`  create  ${path.relative(process.cwd(), dest)}`);
+  }
+}
+
 async function run(args) {
   console.log('\n  syntropic init — Philosophy-as-code development pipeline\n');
 
@@ -261,6 +306,9 @@ async function run(args) {
     actions[tool] = writeOrAppend(fullTpl, appendTpl, destPath, replacements);
   }
 
+  // Scaffold governance docs (.claude/docs/)
+  scaffoldDocs(targetDir, projectName);
+
   // Make health check executable
   const healthScript = path.join(targetDir, 'scripts', 'health-check.js');
   if (fs.existsSync(healthScript)) {
@@ -288,6 +336,7 @@ async function run(args) {
 
   What was created:
 ${toolFiles}
+    .claude/docs/                       Project governance docs (North Star, Backlog, Issues, ADRs)
     .github/workflows/                  Daily health check with auto-remediation
     scripts/health-check.js             Local health check script${hookLine}
 
@@ -299,23 +348,26 @@ ${toolFiles}
     agents, and learning data are always up to date — zero local files to
     maintain. All compute runs on your machine.
 
-  Next steps:
-    1. Review your instruction file and add project-specific context
-    2. Start building! Your AI will follow the EG7 pipeline automatically
+  Your governance docs:
+    .claude/docs/NORTH_STAR.md    Define your vision, goals, and principles
+    .claude/docs/BACKLOG.md       Prioritise and track your work
+    .claude/docs/ISSUES.md        Log bugs and track iterations
+    .claude/docs/adr/             Record architectural decisions
 
-  Telemetry:
-    Syntropic collects pseudonymised usage patterns to improve the methodology
-    for everyone. All identifiers are double-hashed before transmission — no
-    device ID, code, file names, or personal data is ever stored server-side.
-    Run \`syntropic telemetry disable\` to opt out at any time.
+    These are YOUR docs — they stay even if you remove syntropic.
+    Your AI reads them before every cycle and updates them after.
 
-  The methodology is your superpower. Ship and iterate.
+  Next steps:
+    1. Fill in your North Star — vision, mission, and goals
+    2. Review your instruction file and add project-specific context
+    3. Start building! Your AI follows the EG7 pipeline automatically
 
-  Coming soon: \`syntropic analyse\` — assess market opportunity,
-  validate assumptions, and get a strategic way forward, all from
-  your CLI. Your LLM, your compute, powered by 8 philosophy lenses.
+  Trust & privacy:
+    Everything in .claude/ is local and yours. PRISM telemetry is
+    pseudonymised (double-hashed) and opt-out: \`syntropic telemetry disable\`.
+    Remove everything: \`syntropic remove\` (preserves your docs).
 
-  Try the web version now: syntropicworks.com/analyser
+  Run \`syntropic audit\` to see what this methodology catches on your existing code.
 
   Learn more: https://www.syntropicworks.com
 `);

package/commands/remove.js

@@ -0,0 +1,220 @@
+/**
+ * syntropic remove [--force]
+ *
+ * Cleanly remove syntropic from a project.
+ * Preserves user's governance docs (.claude/docs/).
+ * Trust builder — users can always back out.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+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().toLowerCase());
+    });
+  });
+}
+
+function detectSyntropicContent(projectDir) {
+  const found = [];
+
+  // Check CLAUDE.md for syntropic markers
+  const claudeMd = path.join(projectDir, 'CLAUDE.md');
+  if (fs.existsSync(claudeMd)) {
+    const content = fs.readFileSync(claudeMd, 'utf8');
+    if (content.includes('<!-- syntropic -->')) {
+      found.push({ type: 'marker', path: 'CLAUDE.md', desc: 'Syntropic pipeline rules' });
+    }
+  }
+
+  // Check other tool instruction files
+  const toolFiles = ['.cursorrules', '.windsurfrules', '.github/copilot-instructions.md', 'AGENTS.md'];
+  for (const file of toolFiles) {
+    const fullPath = path.join(projectDir, file);
+    if (fs.existsSync(fullPath)) {
+      const content = fs.readFileSync(fullPath, 'utf8');
+      if (content.includes('<!-- syntropic -->')) {
+        found.push({ type: 'marker', path: file, desc: 'Syntropic pipeline rules' });
+      }
+    }
+  }
+
+  // Check .claude/agents/
+  const agentsDir = path.join(projectDir, '.claude', 'agents');
+  if (fs.existsSync(agentsDir)) {
+    const agents = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+    if (agents.length > 0) {
+      found.push({ type: 'dir', path: '.claude/agents/', desc: `${agents.length} pipeline agent${agents.length > 1 ? 's' : ''}` });
+    }
+  }
+
+  // Check post-commit hook
+  const hookPath = path.join(projectDir, '.git', 'hooks', 'post-commit');
+  if (fs.existsSync(hookPath)) {
+    const content = fs.readFileSync(hookPath, 'utf8');
+    if (content.includes('syntropic report')) {
+      found.push({ type: 'hook', path: '.git/hooks/post-commit', desc: 'PRISM cycle reporting' });
+    }
+  }
+
+  // Check health check workflow
+  const workflowDir = path.join(projectDir, '.github', 'workflows');
+  if (fs.existsSync(workflowDir)) {
+    for (const file of fs.readdirSync(workflowDir)) {
+      const content = fs.readFileSync(path.join(workflowDir, file), 'utf8');
+      if (content.includes('syntropic') || content.includes('health-check')) {
+        found.push({ type: 'file', path: `.github/workflows/${file}`, desc: 'Health check workflow' });
+      }
+    }
+  }
+
+  // Check health check script
+  const healthScript = path.join(projectDir, 'scripts', 'health-check.js');
+  if (fs.existsSync(healthScript)) {
+    found.push({ type: 'file', path: 'scripts/health-check.js', desc: 'Health check script' });
+  }
+
+  // Check cache files
+  const cacheFiles = ['.claude/.prism-cache.json', '.claude/.syntropic-config.json'];
+  for (const file of cacheFiles) {
+    if (fs.existsSync(path.join(projectDir, file))) {
+      found.push({ type: 'file', path: file, desc: 'Cache file' });
+    }
+  }
+
+  // Check governance docs (report but don't remove)
+  const docsDir = path.join(projectDir, '.claude', 'docs');
+  if (fs.existsSync(docsDir)) {
+    found.push({ type: 'preserved', path: '.claude/docs/', desc: 'Your project docs (PRESERVED)' });
+  }
+
+  return found;
+}
+
+function removeSyntropicMarkers(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  // Remove everything between <!-- syntropic --> and <!-- /syntropic -->
+  const cleaned = content.replace(/\n*<!-- syntropic -->[\s\S]*?<!-- \/syntropic -->\n*/g, '');
+
+  if (cleaned.trim() === '') {
+    // File was entirely syntropic content — delete it
+    fs.unlinkSync(filePath);
+    return 'deleted';
+  } else {
+    fs.writeFileSync(filePath, cleaned, 'utf8');
+    return 'cleaned';
+  }
+}
+
+function removeSyntropicFromHook(hookPath) {
+  const content = fs.readFileSync(hookPath, 'utf8');
+  const lines = content.split('\n');
+  const cleaned = lines.filter(l =>
+    !l.includes('syntropic report') &&
+    !l.includes('# Syntropic PRISM') &&
+    !l.includes('Disable: syntropic telemetry')
+  ).join('\n');
+
+  if (cleaned.trim() === '#!/bin/sh' || cleaned.trim() === '') {
+    fs.unlinkSync(hookPath);
+    return 'deleted';
+  } else {
+    fs.writeFileSync(hookPath, cleaned, 'utf8');
+    return 'cleaned';
+  }
+}
+
+function removeDir(dirPath) {
+  if (!fs.existsSync(dirPath)) return;
+  fs.rmSync(dirPath, { recursive: true, force: true });
+}
+
+async function run(args) {
+  const force = args.includes('--force');
+  const projectDir = process.cwd();
+
+  console.log('\n  syntropic remove — Clean uninstall\n');
+
+  const found = detectSyntropicContent(projectDir);
+
+  if (found.filter(f => f.type !== 'preserved').length === 0) {
+    console.log('  No syntropic content found in this project.\n');
+    return;
+  }
+
+  // Show what will be affected
+  console.log('  Found:\n');
+  for (const item of found) {
+    if (item.type === 'preserved') {
+      console.log(`    ✓ ${item.path.padEnd(40)} ${item.desc}`);
+    } else {
+      console.log(`    ✗ ${item.path.padEnd(40)} ${item.desc}`);
+    }
+  }
+  console.log('');
+
+  if (!force) {
+    const answer = await ask('  Remove syntropic content? Your docs will be preserved. (y/N) ');
+    if (answer !== 'y' && answer !== 'yes') {
+      console.log('  Cancelled.\n');
+      return;
+    }
+    console.log('');
+  }
+
+  // Remove each item
+  let removed = 0;
+  for (const item of found) {
+    if (item.type === 'preserved') continue;
+
+    const fullPath = path.join(projectDir, item.path);
+
+    try {
+      if (item.type === 'marker') {
+        const result = removeSyntropicMarkers(fullPath);
+        console.log(`  ${result === 'deleted' ? 'delete' : 'clean '}  ${item.path}`);
+        removed++;
+      } else if (item.type === 'hook') {
+        const result = removeSyntropicFromHook(fullPath);
+        console.log(`  ${result === 'deleted' ? 'delete' : 'clean '}  ${item.path}`);
+        removed++;
+      } else if (item.type === 'dir') {
+        removeDir(fullPath);
+        console.log(`  delete  ${item.path}`);
+        removed++;
+      } else if (item.type === 'file') {
+        if (fs.existsSync(fullPath)) {
+          fs.unlinkSync(fullPath);
+          console.log(`  delete  ${item.path}`);
+          removed++;
+        }
+      }
+    } catch (err) {
+      console.log(`  skip    ${item.path} (${err.message})`);
+    }
+  }
+
+  console.log(`\n  Removed ${removed} item${removed !== 1 ? 's' : ''}.`);
+
+  // Check if .claude dir is now empty (except docs)
+  const claudeDir = path.join(projectDir, '.claude');
+  if (fs.existsSync(claudeDir)) {
+    const remaining = fs.readdirSync(claudeDir);
+    const onlyDocs = remaining.length === 1 && remaining[0] === 'docs';
+    if (remaining.length === 0) {
+      fs.rmdirSync(claudeDir);
+      console.log('  Cleaned up empty .claude/ directory.');
+    } else if (onlyDocs) {
+      console.log('  Your project docs in .claude/docs/ have been preserved.');
+    }
+  }
+
+  console.log('');
+}
+
+module.exports = run;

package/commands/report.js

@@ -98,6 +98,42 @@ function autoDetectPhases(weight) {
   }
 }
 
+function detectGovernanceDocs() {
+  const fs = require('fs');
+  const path = require('path');
+  const cwd = process.cwd();
+  const docsDir = path.join(cwd, '.claude', 'docs');
+
+  return {
+    has_north_star: fs.existsSync(path.join(docsDir, 'NORTH_STAR.md')),
+    has_backlog: fs.existsSync(path.join(docsDir, 'BACKLOG.md')),
+    has_issues: fs.existsSync(path.join(docsDir, 'ISSUES.md')),
+    adr_count: (() => {
+      const adrDir = path.join(docsDir, 'adr');
+      if (!fs.existsSync(adrDir)) return 0;
+      return fs.readdirSync(adrDir).filter(f => f.endsWith('.md') && f !== '000-TEMPLATE.md').length;
+    })(),
+  };
+}
+
+function detectGovernanceChanges() {
+  try {
+    const { execSync } = require('child_process');
+    const diff = execSync('git diff --name-only HEAD~1 HEAD 2>/dev/null || echo ""', { encoding: 'utf8' });
+    const changedFiles = diff.trim().split('\n').filter(Boolean);
+    const docChanges = changedFiles.filter(f => f.startsWith('.claude/docs/'));
+
+    return {
+      issues_modified: docChanges.some(f => f.includes('ISSUES')),
+      backlog_updated: docChanges.some(f => f.includes('BACKLOG')),
+      adr_created: docChanges.some(f => f.includes('/adr/')),
+      north_star_updated: docChanges.some(f => f.includes('NORTH_STAR')),
+    };
+  } catch {
+    return { issues_modified: false, backlog_updated: false, adr_created: false, north_star_updated: false };
+  }
+}
+
 function autoDetectSuccess() {
   try {
     const { execSync } = require('child_process');
@@ -156,6 +192,12 @@ async function run(args) {
   const iterations = parseInt(flags.iterations, 10) || 1;
   if (flags.tool) env.tool = flags.tool;
 
+  // Detect governance docs
+  const governance = {
+    ...detectGovernanceDocs(),
+    ...detectGovernanceChanges(),
+  };
+
   // Build the report payload
   const idempotencyKey = crypto.randomUUID();
 
@@ -176,6 +218,7 @@ async function run(args) {
     },
     environment: env,
     project_shape: shapePayload,
+    governance,
   };
 
   // HMAC sign the payload (exclude the hmac field itself)
@@ -202,7 +245,15 @@ async function run(args) {
     await new Promise((resolve) => {
       const req = https.request(options, (res) => {
         if (res.statusCode === 200 || res.statusCode === 201) {
-          console.log(`  PRISM report submitted (${weight} cycle, ${phases.length} phases, ${success ? 'success' : 'failed'}).`);
+          // Honest, useful output
+          const parts = [`Syntropic: ${weight} cycle`, `${shape.changed_count || '?'} files`];
+          if (success) parts.push('build passing');
+          const docUpdates = [];
+          if (governance.issues_modified) docUpdates.push('ISSUES');
+          if (governance.backlog_updated) docUpdates.push('BACKLOG');
+          if (governance.adr_created) docUpdates.push('ADR');
+          if (docUpdates.length > 0) parts.push(`docs: ${docUpdates.join(', ')}`);
+          console.log(`  ${parts.join(' | ')}`);
         } else {
           console.log(`  PRISM report: server returned ${res.statusCode} (non-blocking).`);
         }

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "syntropic",
-  "version": "0.8.1",
-  "description": "Philosophy-as-code development pipeline with market analysis for Claude Code, Cursor, Windsurf, GitHub Copilot, and OpenAI Codex.",
+  "version": "0.9.0",
+  "description": "Ship better software with a proven development methodology. Audit your git history, install disciplined rules, and track iterations — for Claude Code, Cursor, Windsurf, GitHub Copilot, and OpenAI Codex.",
   "bin": {
     "syntropic": "./bin/syntropic.js"
   },
   "keywords": [
     "cli",
     "development-pipeline",
+    "audit",
+    "governance",
+    "project-docs",
     "philosophy-as-code",
     "outcome-thinking",
     "claude-code",

package/templates/CLAUDE.md

@@ -5,6 +5,28 @@
 
 ---
 
+## EG7: Implementation Pipeline (MANDATORY)
+
+Before starting ANY task, state the cycle weight:
+- **Full Cycle** (>3 files or new patterns): /research → /design → /arch → /plan → /dev → /qa → /test
+- **Lightweight Cycle** (1-3 files, known patterns): /research → /plan → /dev → /qa → /test
+- **Minimum Cycle** (trivial/obvious): /dev → /test
+
+**Before coding:** Check `.claude/docs/BACKLOG.md` for current priorities and `.claude/docs/ISSUES.md` for known problems.
+
+---
+
+## EG14: Post-Cycle Documentation (MANDATORY)
+
+After completing work, update:
+- `.claude/docs/ISSUES.md` — log any new issues found during the cycle
+- `.claude/docs/BACKLOG.md` — update status of items worked on
+- `.claude/docs/adr/` — record any architectural decisions made
+
+These updates happen as part of the cycle, not as a separate task.
+
+---
+
 ## EG13: PRISM Sync (MANDATORY)
 
 At the START of every development cycle, before any work:
@@ -19,6 +41,7 @@ At the START of every development cycle, before any work:
    - `cycle_recommendations`: adjust cycle weight if triggers match
    - `phase_guidance`: follow the instruction for each phase you run
    - `patterns`: prefer efficient patterns, avoid wasteful ones
+   - `config_version` + `last_updated`: if >7 days old, methodology may be stale
 
 3. At cycle END (after test phase passes or cycle completes):
    Run: `syntropic report`
@@ -60,3 +83,4 @@ Never ask permission for:
 
 <!-- Generated by syntropic — development methodology for AI coding tools (https://npmjs.com/package/syntropic) -->
 <!-- Research: https://zenodo.org/records/17894441 -->
+<!-- /syntropic -->

package/templates/agents-md.template

@@ -5,6 +5,18 @@
 
 ---
 
+## Development Pipeline (MANDATORY)
+
+Before starting ANY task, state the cycle weight:
+- Full Cycle (>3 files): research → design → arch → plan → dev → qa → test
+- Lightweight (1-3 files): research → plan → dev → qa → test
+- Minimum (trivial): dev → test
+
+Before coding: check `.claude/docs/BACKLOG.md` and `.claude/docs/ISSUES.md`.
+After completing: update ISSUES.md, BACKLOG.md, and ADRs as needed.
+
+---
+
 ## PRISM Sync (MANDATORY)
 
 At the START of every development cycle, fetch the methodology by reading this URL:
@@ -41,3 +53,4 @@ If the fetch fails, use these fallback rules:
 
 <!-- Generated by syntropic — development methodology for AI coding tools (https://npmjs.com/package/syntropic) -->
 <!-- Research: https://zenodo.org/records/17894441 -->
+<\!-- /syntropic -->

package/templates/claude-append.template

@@ -4,6 +4,16 @@
 <!-- syntropic -->
 ---
 
+## Development Pipeline (MANDATORY)
+
+Before starting ANY task, state the cycle weight:
+- Full Cycle (>3 files): research → design → arch → plan → dev → qa → test
+- Lightweight (1-3 files): research → plan → dev → qa → test
+- Minimum (trivial): dev → test
+
+Before coding: check `.claude/docs/BACKLOG.md` and `.claude/docs/ISSUES.md`.
+After completing: update ISSUES.md, BACKLOG.md, and ADRs as needed.
+
 ## EG13: PRISM Sync (MANDATORY)
 
 At the START of every development cycle, fetch the methodology:

package/templates/copilot-instructions.template

@@ -3,6 +3,16 @@
 
 These instructions are loaded automatically by GitHub Copilot. Follow them for all work in this project.
 
+## Development Pipeline (MANDATORY)
+
+Before starting ANY task, state the cycle weight:
+- Full Cycle (>3 files): research → design → arch → plan → dev → qa → test
+- Lightweight (1-3 files): research → plan → dev → qa → test
+- Minimum (trivial): dev → test
+
+Before coding: check `.claude/docs/BACKLOG.md` and `.claude/docs/ISSUES.md`.
+After completing: update ISSUES.md, BACKLOG.md, and ADRs as needed.
+
 ## PRISM Sync (MANDATORY)
 
 At the START of every development cycle, fetch the methodology by reading this URL:
@@ -34,3 +44,4 @@ If the fetch fails, use these fallback rules:
 
 <!-- Generated by syntropic — development methodology for AI coding tools (https://npmjs.com/package/syntropic) -->
 <!-- Research: https://zenodo.org/records/17894441 -->
+<\!-- /syntropic -->

package/templates/cursorrules.template

@@ -5,6 +5,18 @@
 
 ---
 
+## Development Pipeline (MANDATORY)
+
+Before starting ANY task, state the cycle weight:
+- Full Cycle (>3 files): research → design → arch → plan → dev → qa → test
+- Lightweight (1-3 files): research → plan → dev → qa → test
+- Minimum (trivial): dev → test
+
+Before coding: check `.claude/docs/BACKLOG.md` and `.claude/docs/ISSUES.md`.
+After completing: update ISSUES.md, BACKLOG.md, and ADRs as needed.
+
+---
+
 ## PRISM Sync (MANDATORY)
 
 At the START of every development cycle, fetch the methodology by reading this URL:
@@ -40,3 +52,4 @@ If the fetch fails, use these fallback rules:
 
 <!-- Generated by syntropic — development methodology for AI coding tools (https://npmjs.com/package/syntropic) -->
 <!-- Research: https://zenodo.org/records/17894441 -->
+<\!-- /syntropic -->

package/templates/docs/BACKLOG.template

@@ -0,0 +1,40 @@
+# {{PROJECT_NAME}} — Backlog
+
+**Last Updated:** {{CREATED_DATE}}
+**Source of truth for prioritised work.**
+
+---
+
+## In Progress
+
+### [ITEM-1]: [Title]
+**Priority:** P0 | **Effort:** Small | **Status:** Building
+- [What's being built]
+- [Key decisions or constraints]
+
+---
+
+## Next Up
+
+### [ITEM-2]: [Title]
+**Priority:** P1 | **Effort:** Medium | **Depends on:** ITEM-1
+- [What needs to happen]
+
+---
+
+## Backlog
+
+### [ITEM-3]: [Title]
+**Priority:** P2 | **Effort:** [Small/Medium/Large]
+- [Description]
+
+---
+
+## Done (Recent)
+
+- [x] [Completed item with date]
+
+---
+
+_Update after every cycle. Move items between sections as status changes._
+_Your AI assistant checks this before starting work (EG7) and updates it after (EG14)._

package/templates/docs/ISSUES.template

@@ -0,0 +1,51 @@
+# {{PROJECT_NAME}} — Issue Log
+
+**Last Updated:** {{CREATED_DATE}}
+
+---
+
+## Active Issues
+
+_No issues yet. When something breaks or needs investigation, log it here._
+
+<!--
+### ISSUE-001: [Title]
+**Status:** Open | In Progress | Resolved
+**Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Created:** YYYY-MM-DD
+
+**Description:**
+[What is the issue?]
+
+**Resolution:**
+[How was/will it be fixed?]
+-->
+
+---
+
+## Resolved Issues
+
+_Resolved issues stay here as a record. They help track iteration patterns._
+
+---
+
+## Issue Template
+
+```markdown
+### ISSUE-XXX: [Title]
+**Status:** Open | In Progress | Resolved | Won't Fix
+**Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Created:** YYYY-MM-DD
+**Resolved:** YYYY-MM-DD (if resolved)
+
+**Description:**
+[What is the issue?]
+
+**Resolution:**
+[How was/will it be fixed?]
+```
+
+---
+
+_Log issues as you find them. Your AI assistant checks this before starting work (EG7)._
+_Each fix commit that references an issue here is a measurable iteration._

package/templates/docs/NORTH_STAR.template

@@ -0,0 +1,73 @@
+# {{PROJECT_NAME}} — North Star
+
+**Created:** {{CREATED_DATE}}
+**Status:** Active
+
+---
+
+## Vision
+
+_What does this project exist to achieve? One sentence._
+
+> [Your vision statement here]
+
+---
+
+## Mission
+
+_How will you get there? The approach._
+
+> [Your mission statement here]
+
+---
+
+## Goals (Prioritised)
+
+### G1: [Primary Goal]
+**Priority:** Primary
+
+[What does success look like? How will you measure it?]
+
+### G2: [Secondary Goal]
+**Priority:** Secondary
+
+[What does success look like? How will you measure it?]
+
+### G3: [Learning Goal]
+**Priority:** Always
+
+[What are you learning by building this?]
+
+---
+
+## Design Principles
+
+### DP1: [Principle Name]
+[One sentence explaining the principle and why it matters.]
+
+### DP2: [Principle Name]
+[One sentence explaining the principle and why it matters.]
+
+### DP3: [Principle Name]
+[One sentence explaining the principle and why it matters.]
+
+---
+
+## Anti-Patterns
+
+- **AP1**: [What to avoid and why]
+- **AP2**: [What to avoid and why]
+- **AP3**: [What to avoid and why]
+
+---
+
+## Current State
+
+| Area | Status | Next Step |
+|------|--------|-----------|
+| [Area 1] | [Status] | [Next action] |
+| [Area 2] | [Status] | [Next action] |
+
+---
+
+_Update this document when priorities shift. Your AI assistant reads this at the start of every cycle._

package/templates/docs/adr/000-TEMPLATE.template

@@ -0,0 +1,39 @@
+# ADR-XXX: [Title]
+
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** YYYY-MM-DD
+**Author:** [Name]
+**Supersedes:** ADR-XXX (if applicable)
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+### Positive
+-
+
+### Negative
+-
+
+### Risks
+-
+
+## Alternatives Considered
+
+What other options were considered and why were they rejected?
+
+| Option | Pros | Cons | Why Rejected |
+|--------|------|------|--------------|
+| | | | |
+
+## References
+
+- [Link to relevant documentation]

package/templates/tool-append.template

@@ -4,6 +4,16 @@
 <!-- syntropic -->
 ---
 
+## Development Pipeline (MANDATORY)
+
+Before starting ANY task, state the cycle weight:
+- Full Cycle (>3 files): research → design → arch → plan → dev → qa → test
+- Lightweight (1-3 files): research → plan → dev → qa → test
+- Minimum (trivial): dev → test
+
+Before coding: check `.claude/docs/BACKLOG.md` and `.claude/docs/ISSUES.md`.
+After completing: update ISSUES.md, BACKLOG.md, and ADRs as needed.
+
 ## PRISM Sync (MANDATORY)
 
 At the START of every development cycle, fetch the methodology by reading this URL:

package/templates/windsurfrules.template

@@ -5,6 +5,18 @@
 
 ---
 
+## Development Pipeline (MANDATORY)
+
+Before starting ANY task, state the cycle weight:
+- Full Cycle (>3 files): research → design → arch → plan → dev → qa → test
+- Lightweight (1-3 files): research → plan → dev → qa → test
+- Minimum (trivial): dev → test
+
+Before coding: check `.claude/docs/BACKLOG.md` and `.claude/docs/ISSUES.md`.
+After completing: update ISSUES.md, BACKLOG.md, and ADRs as needed.
+
+---
+
 ## PRISM Sync (MANDATORY)
 
 At the START of every development cycle, fetch the methodology by reading this URL:
@@ -40,3 +52,4 @@ If the fetch fails, use these fallback rules:
 
 <!-- Generated by syntropic — development methodology for AI coding tools (https://npmjs.com/package/syntropic) -->
 <!-- Research: https://zenodo.org/records/17894441 -->
+<\!-- /syntropic -->