sdg-agents 1.2.6 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdg-agents",
-  "version": "1.2.6",
+  "version": "1.10.0",
   "description": "Structured working protocol and engineering rules for AI agents. Works with Claude Code, Antigravity, Codex, and others.",
   "type": "module",
   "main": "./src/engine/bin/index.mjs",
@@ -14,7 +14,7 @@
     "dev": "node src/engine/bin/index.mjs",
     "build": "node src/engine/bin/build-bundle.mjs",
     "review": "node src/engine/bin/review-bundle.mjs",
-    "bump": "node src/engine/bin/auto-bump.mjs",
+    "bump": "node scripts/bump.mjs",
     "add-idiom": "node src/engine/bin/add-idiom.mjs",
     "clear": "node src/engine/bin/clear-bundle.mjs",
     "test": "node --test src/engine/lib/*.test.mjs",

package/src/assets/instructions/commands/sdg-end.md

@@ -12,20 +12,19 @@ Write one sentence per completed PLAN task. If no PLAN existed (e.g. `[S]` tasks
 
 ## Step 2 — CHANGELOG
 
-- Append an entry under `## [Unreleased]` in `CHANGELOG.md`:
-
-1. **Identify Version**: Check `package.json` (or equivalent) for the current version.
-2. **Calculate Next**: Determine the next version (patch/minor) based on the cycle type (`feat` → minor/patch, `fix` → patch).
-3. **Update Header**:
-   - If the project uses auto-bump or a release is intended: Create/Update the header to `## [NEXT_VERSION] - YYYY-MM-DD`.
-   - Otherwise: Append under `## [Unreleased]`.
-4. **Append Entry**:
-   - `feat:` cycle → `### Added`
-   - `fix:` cycle → `### Fixed`
-   - `docs:` cycle → skip this step
-   - `land:` cycle → skip this step
-
-If `## [Unreleased]` (or the appropriate version header) does not exist, create it above the most recent entry.
+Prepare your technical narrative in the `CHANGELOG.md`.
+
+1. **Identify Strategy**:
+   - **Automated**: If `auto-bump.mjs` exists, you **MUST** first manually populate the `## [Unreleased]` section with your technical narrative. The automated pipeline will promote this content to the new version header during the commit. **DO NOT commit with an empty [Unreleased] section.**
+   - **Manual**: If no automation is present, you must promote the header manually (e.g., `## [1.2.0] - 2026-04-11`) or run the designated `bump` script.
+
+2. **Append Entry**:
+   - `feat:` cycle → Add under `### Added`
+   - `fix:` cycle → Add under `### Fixed`
+   - `docs:` cycle → Optional (for major architectural docs)
+   - `land:` cycle → Skip
+
+3. **Verify Header**: Ensure `## [Unreleased]` exists at the top. If missing, create it above the most recent version entry.
 
 ## Step 3 — BACKLOG: tasks.md
 

package/src/assets/instructions/core/writing-soul.md

@@ -1,82 +1,45 @@
-# Writing Soul — Professional Authority Standards
+# The Writing Soul
 
-> [!IMPORTANT]
-> **GOVERNANCE MANDATE**
-> This specification applies to all **non-code writing tasks**, including READMEs, Guides, UI Content, CHANGELOGs, and Commit Messages.
-> The goal is to eliminate "AI Slop" and restore **Developer intentionality**, density, and soul to every project artifact.
+Good technical writing starts with the realization that there is a person on both sides of the screen. We believe that software documentation is a shared conversation, and maintaining a sense of mind behind the words is essential for effective communication. Sterile or voiceless text often feels like a missed opportunity to connect and share real engineering wisdom. These standards apply to all non-code writing tasks, including READMEs, guides, UI content, and commit messages.
 
-## 1. Personality and Soul
+## Cultivating Personality
 
-Good technical writing has a **mind** behind it. Sterile, voiceless writing is as obvious as low-density slop.
+Effective writing reflects the natural rhythms of how we think and solve problems. You can bring a sense of purpose to your text by offering a clear perspective on the facts you present. Mixing brief observations with longer, more detailed explanations helps keep the reader engaged.
 
-- **Have opinions**: Don't just report facts — react to them.
-- **Vary your rhythm**: Mix short, punchy sentences with longer, flowing ones.
-- **Acknowledge complexity**: Real professionals have mixed feelings and uncertainty.
-- **Let some mess in**: Perfectly algorithmic structure feels fake. Tangents and asides add pulse.
+Authenticity also comes from acknowledging that engineering is complex. Professionals often navigate uncertainty or hold nuanced views on a topic, and reflecting those feelings makes your writing more reliable. Allowing space for a well-placed aside or a brief tangent can create the pulse that makes a technical guide feel alive and uniquely human.
 
----
-
-## 2. Content Patterns to Eliminate
-
-### I. Significance Inflation
+## Seeking Authenticity
 
-**Banned phrases**: "testament/reminder to", "pivotal moment", "is a testament/reminder", "evolving landscape", "underscores its significance".
-**Fix**: Remove the "puffery". Just state the facts and their direct consequences.
+Maintaining a professional and grounded tone involves recognizing patterns that sometimes cloud the clarity of our message. We can improve our writing by focusing on direct observations rather than relying on stylistic crutches.
 
-### II. Superficial -ing Endings
+### Natural Expression
 
-**Patterns**: "...highlighting X", "...ensuring Y", "...reflecting Z".
-**Fix**: Break into clear, active clauses. Avoid tacking on "fake depth" via present participle phrases.
+True authority often speaks for itself. We can avoid significance inflation by stating facts and their direct consequences, allowing the quality of the work to be the primary focus. Using phrases like "testament to" or "pivotal moment" often adds unnecessary weight where a simple description of the impact would be more effective.
 
-### III. Promotional & Sycophantic Tone
+### Active Clarity
 
-**Banned adjectives**: "vibrant", "rich", "groundbreaking", "breathtaking", "seamless".
-**Banned artifacts**: "Great question!", "I hope this helps!", "Certainly!".
-**Fix**: Maintain a professional, peer-to-level tone. No sales pitch, no servility.
+Direct communication is usually the most helpful for the reader. We can sharpen our message by breaking complex ideas into clear, active clauses. While present participle phrases ending in "-ing" are common, they sometimes obscure the relationship between actions. Choosing active verbs helps ensure the reader understands the exact flow of information or logic.
 
-### IV. Generic Positive Conclusions
-
-**Patterns**: "The future looks bright", "Exciting times lie ahead".
-**Fix**: End with a concrete next step or a specific fact about future plans.
-
----
+### Professional Peerage
 
-## 3. Language & Style Hardening
+We value a tone that respects the expertise of the reader. A calm and peer-to-level approach builds trust more effectively than using promotional adjectives like "vibrant" or "groundbreaking." This same principle applies to our interactions, where a professional and direct response carries more weight than conversational fillers or overly decorative enthusiasm.
 
-### I. Copula Avoidance
+## Language and Style Practices
 
-**Stop**: "serves as", "stands as", "represents [a]".
-**Use**: "is", "are", "has". Simple is more direct.
+The way we structure our language influences how easily a reader can follow our logic. We prefer simple and direct verbs to keep the focus on the content. Words like "is," "are," and "has" are often more effective than complex alternatives that can slow down the reading experience.
 
-### II. Em Dash & Boldface Overuse
+### Visual Serenity
 
-**Rule**: Em dashes (—) are banned. No exceptions. AI uses them constantly to fake rhetorical punch.
-**Fix**: Rewrite with a comma, a period, or a new sentence. If it needs a pause, earn it with structure.
-Bold is for true technical emphasis only: a term, a command, a key constraint. Not decoration.
-
-### III. Title Case & Emojis
-
-**Rule**: No Title Case for everything. Emojis are reserved for **pattern signaling only** — marking BAD/GOOD examples, callouts, or explicit visual cues in documentation.
-**Banned**: Decorative emojis in section headers, link anchors, or inline prose (e.g. `## 🚀 Quick Start`, `✨ Try the app`).
-**Allowed**: Signal emojis that carry semantic meaning in structured examples:
-
-- `BAD`: `❌ if (data == null)` / `GOOD`: `✅ if (!data)`
-- `[!WARNING]`, `[!TIP]`, `[!NOTE]` callouts (GitHub-native, not emoji)
-  **Fix**: Use Sentence case for headings. Strip all decorative emoji. If a header needs visual weight, use formatting — not icons.
-
----
+Structure and rhythm should guide the reader through the text naturally. We find that avoiding em dashes encourages a more thoughtful sentence structure, as it requires earning each pause through careful composition. Similarly, we use bold formatting exclusively for technical emphasis, such as specific terms, commands, or key constraints.
 
-## 4. The Authority Loop
+Our approach to formatting also prioritizes clarity. Headings follow sentence case to maintain a serene and professional appearance. We use emojis only when they carry semantic meaning for pattern signaling, such as marking successful or unsuccessful examples in a technical guide. This keeps the visual environment focused on the information being shared.
 
-Before finalizing any content, perform a self-audit:
+## The Refinement Process
 
-1. **Identify Patterns**: Scan for the AI-isms listed above.
-2. **Rewrite**: Replace slop with direct, active voice.
-3. **Add Soul**: Inject a specific observation or a varied rhythm.
-4. **Final Check**: Ask: _"What makes this so obviously AI-generated?"_ Fix the remaining tells.
+Before sharing your work, a brief moment of reflection can help ensure the content reflects your intention. You might find it helpful to look for familiar patterns that feel more like general summaries than specific observations. Replacing these with active, direct language often makes the writing feel more genuine. Adding a unique insight or varying the length of your sentences can provide the final touch that makes the text feel truly yours.
 
 ---
 
-## Reference & Credits
+## Reference and Credits
 
-This specification is based on the **Wikipedia:Signs of AI writing** project, maintained by **WikiProject AI Cleanup**. It serves as the foundational standard for eliminating statistical slop and restoring **Developer intentionality** to generated text.
+This standard is inspired by the collective efforts of the project to eliminate statistical slop and restore intentionality to generated text. It serves as a foundation for building clear, purposeful, and human-centered documentation across the entire ecosystem.

package/src/assets/instructions/templates/bump.mjs

@@ -0,0 +1,89 @@
+/**
+ * SDG-Agents: Bump & Changelog Automation
+ * Automates semantic versioning and promotes Unreleased changes in CHANGELOG.md.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const ROOT_DIR = process.cwd();
+const PACKAGE_JSON_PATH = path.join(ROOT_DIR, 'package.json');
+const CHANGELOG_PATH = path.join(ROOT_DIR, 'CHANGELOG.md');
+
+function run() {
+  const args = process.argv.slice(2);
+  const bumpType = args[0]; // feat, fix, major
+
+  if (!['feat', 'fix', 'major'].includes(bumpType)) {
+    console.error('❌ Error: Please specify bump type (feat, fix, or major).');
+    console.log('Usage: npm run bump <feat|fix|major>');
+    process.exit(1);
+  }
+
+  const typeMap = {
+    feat: 'minor',
+    fix: 'patch',
+    major: 'major',
+  };
+
+  const npmType = typeMap[bumpType];
+
+  try {
+    // 1. Get current version
+    const pkg = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, 'utf8'));
+    const oldVersion = pkg.version;
+
+    // 2. Bump version in package.json (no git tag/commit yet)
+    console.log(`🚀 Bumping version (${npmType})...`);
+    execSync(`npm version ${npmType} --no-git-tag-version`, { stdio: 'inherit' });
+
+    // 3. Get new version
+    const newPkg = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, 'utf8'));
+    const newVersion = newPkg.version;
+
+    // 4. Update CHANGELOG.md
+    updateChangelog(newVersion);
+
+    console.log(`✅ Success: ${oldVersion} → ${newVersion}`);
+    console.log('🔗 CHANGELOG.md updated and promoted to current date.');
+  } catch (error) {
+    console.error('❌ Error during bump strategy:', error.message);
+    process.exit(1);
+  }
+}
+
+function updateChangelog(newVersion) {
+  if (!fs.existsSync(CHANGELOG_PATH)) {
+    console.warn('⚠️  CHANGELOG.md not found. Skipping changelog update.');
+    return;
+  }
+
+  const content = fs.readFileSync(CHANGELOG_PATH, 'utf8');
+  const today = new Date().toISOString().split('T')[0];
+
+  // Pattern to find the [Unreleased] section
+  const unreleasedRegex = /##\s*\[Unreleased\](\s*-\s*\d{4}-\d{2}-\d{2})?/i;
+
+  if (!unreleasedRegex.test(content)) {
+    console.warn('⚠️  Could not find "## [Unreleased]" header in CHANGELOG.md.');
+    console.log('Skipping content promotion.');
+    return;
+  }
+
+  const newHeader = `## [${newVersion}] - ${today}`;
+
+  // 1. Promote Unreleased to New Version
+  let updatedContent = content.replace(unreleasedRegex, newHeader);
+
+  // 2. Inject new [Unreleased] block at the top
+  const insertIndex = updatedContent.indexOf(newHeader);
+  const nextBlock = `## [Unreleased]\n\n### Added\n\n### Fixed\n\n`;
+
+  updatedContent =
+    updatedContent.slice(0, insertIndex) + nextBlock + updatedContent.slice(insertIndex);
+
+  fs.writeFileSync(CHANGELOG_PATH, updatedContent);
+}
+
+run();

package/src/assets/instructions/templates/workflow.md

@@ -140,7 +140,8 @@ On every request, classify intent before acting:
 ### END Checklist (mandatory — execute in order, mark each before proceeding)
 
 - [ ] **SUMMARIZE** — one sentence per completed PLAN task written in response
-- [ ] **CHANGELOG** — Append entry. **Identify next version** (check \`package.json\`) to determine the header (\`## [NEXT_VERSION] - YYYY-MM-DD\` for releases/auto-bump, or \`## [Unreleased]\`). Categories: \`### Added\` (feat), \`### Fixed\` (fix).
+- [ ] **BUMP** — run \`npm run bump <feat|fix>\` to promote CHANGELOG and package.json version. Skip if not applicable.
+- [ ] **CHANGELOG** — Verify [Unreleased] content was promoted. Append any manual notes if needed.
 - [ ] **BACKLOG: tasks.md** — all completed tasks moved to `## Done` with `[DONE]` status
 - [ ] **BACKLOG: context.md** — \`## Now\` updated with next objective or cleared
 - [ ] **KNOWLEDGE** — Log any patterns, findings, or rework discovered during this cycle. Update \`.ai-backlog/learned.md\` (for successful feats) or \`.ai-backlog/troubleshoot.md\` (for fixed incidents). Curate stale or irrelevant items.

package/src/engine/bin/auto-bump.mjs

@@ -12,6 +12,7 @@ const { runIfDirect } = FsUtils;
 // bin/ → engine/ → src/ → root
 const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../');
 const PACKAGE_PATHS = [path.join(ROOT_DIR, 'package.json')];
+const CHANGELOG_PATH = path.join(ROOT_DIR, 'CHANGELOG.md');
 
 // --- Orchestrator ---
 
@@ -27,7 +28,13 @@ async function run() {
   const rootPkg = readPackageJson(resolveRootPackagePath());
   const nextVersion = bumpVersion(rootPkg.version, bumpType);
 
+  // 1. Promote Changelog
+  updateChangelog(nextVersion);
+
+  // 2. Sync Package.json files
   syncAllPackages(nextVersion);
+
+  // 3. Commit the bump
   stageAndCommit(nextVersion);
 
   console.log(`  auto-bump: ${rootPkg.version} → ${nextVersion} (${bumpType})`);
@@ -57,9 +64,37 @@ function bumpVersion(current, bumpType) {
       return `${major}.${minor + 1}.0`;
     case 'patch':
       return `${major}.${minor}.${patch + 1}`;
+    default:
+      return current;
   }
 }
 
+function updateChangelog(newVersion) {
+  if (!fs.existsSync(CHANGELOG_PATH)) return;
+
+  const content = fs.readFileSync(CHANGELOG_PATH, 'utf8');
+  const today = new Date().toISOString().split('T')[0];
+
+  // Pattern to find the [Unreleased] section
+  const unreleasedRegex = /##\s*\[Unreleased\](\s*-\s*\d{4}-\d{2}-\d{2})?/i;
+
+  if (!unreleasedRegex.test(content)) return;
+
+  const newHeader = `## [${newVersion}] - ${today}`;
+
+  // 1. Promote Unreleased to New Version
+  let updatedContent = content.replace(unreleasedRegex, newHeader);
+
+  // 2. Inject new [Unreleased] block at the top if it was promoted
+  const insertIndex = updatedContent.indexOf(newHeader);
+  const nextBlock = `## [Unreleased]\n\n### Added\n\n### Fixed\n\n`;
+
+  updatedContent =
+    updatedContent.slice(0, insertIndex) + nextBlock + updatedContent.slice(insertIndex);
+
+  fs.writeFileSync(CHANGELOG_PATH, updatedContent);
+}
+
 // --- Sync & Commit ---
 
 function syncAllPackages(nextVersion) {
@@ -71,7 +106,8 @@ function syncAllPackages(nextVersion) {
 
 function stageAndCommit(nextVersion) {
   const paths = resolvePackagePaths();
-  const files = paths.filter((p) => fs.existsSync(p)).join(' ');
+  const files = [...paths, CHANGELOG_PATH].filter((p) => fs.existsSync(p)).join(' ');
+
   execSync(`git add ${files}`, { stdio: 'inherit' });
   execSync(`git commit -m "chore: bump version to ${nextVersion}"`, { stdio: 'inherit' });
 }

package/src/engine/bin/build-bundle.mjs

@@ -21,6 +21,7 @@ const {
   writeBacklogFiles,
   writeGitignore,
   writeManifest,
+  writeAutomationScripts,
 } = InstructionAssembler;
 const { success } = ResultUtils;
 const { runIfDirect } = FsUtils;
@@ -207,6 +208,7 @@ function executeQuickPipeline(targetDir, selections, { noDevGuides = false } = {
 
   printStep(5, 5, 'Injecting spec templates...');
   injectPrompts(targetDir, selections.track);
+  writeAutomationScripts(targetDir, selections);
   writeManifest(targetDir, selections, packageJson.version);
 }
 
@@ -239,6 +241,7 @@ function executeAgentsPipeline(targetDir, selections, { noDevGuides = false } =
   writeGitignore(targetDir);
 
   printStep(5, 5, 'Finalizing manifest...');
+  writeAutomationScripts(targetDir, selections);
   writeManifest(targetDir, selections, packageJson.version);
 }
 

package/src/engine/bin/check-narrative.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * Narrative Guard — Blocks feat: and fix: commits if CHANGELOG.md [Unreleased] is empty.
+ * Ensures the auto-bump pipeline always has content to promote.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { execSync } from 'node:child_process';
+
+const PROJECT_ROOT = process.cwd();
+const CHANGELOG_PATH = path.join(PROJECT_ROOT, 'CHANGELOG.md');
+
+async function run() {
+  const commitMsgFile = process.argv[2];
+  if (!commitMsgFile) {
+    console.error('  ❌ Error: No commit message file provided.');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(commitMsgFile)) {
+    console.error(`  ❌ Error: Commit message file not found at ${commitMsgFile}`);
+    process.exit(1);
+  }
+
+  const commitMsg = fs.readFileSync(commitMsgFile, 'utf8').trim();
+  const firstLine = commitMsg.split('\n')[0].trim();
+
+  // ONLY target feat: and fix: (SDG Cycle Triggers) as per maintainer instruction
+  const isSdgTrigger = /^feat:/.test(firstLine) || /^fix:/.test(firstLine);
+  if (!isSdgTrigger) {
+    process.exit(0);
+  }
+
+  let changelog = '';
+  try {
+    // Read STAGED version of CHANGELOG.md to prevent issues with lint-staged or stashing
+    changelog = execSync('git show :CHANGELOG.md', {
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).toString();
+  } catch {
+    // Fallback to disk if not in index (shouldn't happen in a commit hook for a tracked file)
+    if (fs.existsSync(CHANGELOG_PATH)) {
+      changelog = fs.readFileSync(CHANGELOG_PATH, 'utf8');
+    }
+  }
+
+  if (!changelog) {
+    console.warn('  ⚠️  Warning: CHANGELOG.md not found or empty. Skipping narrative check.');
+    process.exit(0);
+  }
+
+  // Extract content between [Unreleased] and the next version header (## [...) or end of file
+  // We use (?=\n##\s) to match the next level-2 header specifically, avoiding matches on ### sub-headers.
+  const unreleasedMatch = changelog.match(
+    /##\s*\[Unreleased\].*?\n([\s\S]*?)(?=\n##\s|(?:\n){0,1}$)/i
+  );
+
+  if (!unreleasedMatch) {
+    console.error('\n  ❌ NARRATIVE VIOLATION: "## [Unreleased]" section missing in CHANGELOG.md.');
+    console.error('  SDG cycles (feat/fix) MUST have a technical narrative before committing.\n');
+    process.exit(1);
+  }
+
+  const narrative = unreleasedMatch[1]
+    .replace(/###\s*(Added|Fixed|Changed|Removed|Security|Deprecated)/gi, '')
+    .replace(/<!--[\s\S]*?-->/g, '') // Remove markdown comments
+    .trim();
+
+  // If the narrative is just whitespace or empty after removing headers/comments
+  if (!narrative || narrative.length < 3) {
+    console.error('\n  ❌ NARRATIVE VIOLATION: The [Unreleased] section is empty.');
+    console.error('  You are committing a "feat:" or "fix:" which triggers a version bump.');
+    console.error('  Please document your changes in CHANGELOG.md under [Unreleased] first.\n');
+    process.exit(1);
+  }
+
+  console.log('  ✅ Narrative Guard: CHANGELOG.md validated.');
+  process.exit(0);
+}
+
+run().catch((err) => {
+  console.error('  ❌ Narrative Guard Exception:', err.message);
+  process.exit(1);
+});
+// test

package/src/engine/bin/check-sync.mjs

@@ -13,13 +13,12 @@ import crypto from 'node:crypto';
 import { FsUtils } from '../lib/fs-utils.mjs';
 import { ResultUtils } from '../lib/result-utils.mjs';
 
-const { getDirname, runIfDirect } = FsUtils;
+const { runIfDirect } = FsUtils;
 const { success, fail } = ResultUtils;
 
-const __dirname = getDirname(import.meta.url);
-const MONOREPO_ROOT = path.join(__dirname, '..', '..', '..', '..', '..');
-const ASSETS_DIR = path.join(MONOREPO_ROOT, 'packages', 'cli', 'src', 'assets', 'instructions');
-const AI_DIR = path.join(MONOREPO_ROOT, 'packages', 'cli', '.ai', 'instructions');
+const PROJECT_ROOT = process.cwd();
+const ASSETS_DIR = path.join(PROJECT_ROOT, 'src', 'assets', 'instructions');
+const AI_DIR = path.join(PROJECT_ROOT, '.ai', 'instructions');
 
 // why: flavor/ in .ai/ is populated by renaming flavors/{id}/ — no direct mirror exists in src/assets/flavor/
 const MIRRORED_DIRS = ['core', 'idioms', 'templates', 'competencies'];

package/src/engine/bin/index.mjs

@@ -39,6 +39,11 @@ async function run() {
   // Resolve target directory early for the entire cycle
   args.targetDir = path.resolve(args.targetDir || process.cwd());
 
+  // Maintainer Protocol: ensuring core instructions are synced to .ai/ for the agent
+  if (!args.subcommand && !args.help && !args.version) {
+    await ensureMaintainerSync(args.targetDir);
+  }
+
   if (args.subcommand) {
     await executeSubcommand(args);
   } else {
@@ -210,6 +215,35 @@ async function runSettingsMenu(targetDir) {
 
 // --- System ---
 
+async function ensureMaintainerSync(targetDir) {
+  const { isMaintainerMode } = PromptUtils;
+  if (!isMaintainerMode()) return;
+
+  const { SyncChecker } = await import('./check-sync.mjs');
+  const syncResult = SyncChecker.run();
+
+  if (syncResult.isFailure) {
+    console.log('\n  🛠️  MAINTAINER MODE: Drift detected in core instructions.');
+    console.log('  🔄 Automatic sync in progress...\n');
+
+    const { ManifestUtils } = await import('../lib/manifest-utils.mjs');
+    const { SDG } = await import('./build-bundle.mjs');
+    const manifest = ManifestUtils.loadManifest(targetDir);
+
+    if (manifest) {
+      try {
+        await SDG.run(targetDir, { selections: manifest.selections });
+        console.log('\n  ✅ Core instructions synchronized. Agent rules are up-to-date.\n');
+        console.log('─'.repeat(50) + '\n');
+      } catch (error) {
+        console.log(`\n  ⚠️  Automatic sync failed: ${error.message}\n`);
+      }
+    } else {
+      console.log('  ⚠️  Cannot auto-sync: No manifest found. Run "init" once.\n');
+    }
+  }
+}
+
 function handleExitError(error) {
   if (error.message?.includes('force closed') || error.name === 'ExitPromptError') {
     console.log('\n\n  👋 Goodbye! See you soon engineer.');

package/src/engine/lib/cli-parser.mjs

@@ -17,6 +17,7 @@ function parseCliArgs(argv) {
     mode: getArgValue(argv, '--mode'),
     track: getArgValue(argv, '--track'),
     scope: getArgValue(argv, '--scope'),
+    bump: !argv.includes('--no-bump'),
   };
 }
 

package/src/engine/lib/instruction-assembler.mjs

@@ -528,6 +528,75 @@ function writeManifest(targetDir, selections, pkgVersion) {
   fs.writeFileSync(path.join(aiDir, '.sdg-manifest.json'), JSON.stringify(manifest, null, 2));
 }
 
+/**
+ * Injects automation scripts and configurations (Bump, Husky) if enabled.
+ * Idempotent: skips if scripts/bump.mjs exists or if selections.bump is false.
+ */
+function writeAutomationScripts(targetDir, selections) {
+  if (selections.bump === false) return;
+
+  const scriptsDir = path.join(targetDir, 'scripts');
+  const bumpScriptPath = path.join(scriptsDir, 'bump.mjs');
+
+  // 1. Check for existing bump script in package.json to avoid collision
+  const pkgPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return;
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const hasExistingBump =
+    pkg.scripts && (pkg.scripts.bump || pkg.scripts.release || pkg.scripts.version);
+
+  if (hasExistingBump && !fs.existsSync(bumpScriptPath)) {
+    // If they have a script but not our file, we respect their script
+    return;
+  }
+
+  // 2. Write bump.mjs template
+  if (!fs.existsSync(bumpScriptPath)) {
+    if (!fs.existsSync(scriptsDir)) fs.mkdirSync(scriptsDir, { recursive: true });
+    const templatePath = path.join(SOURCE_INSTRUCTIONS, 'templates', 'bump.mjs');
+    const templateContent = fs.readFileSync(templatePath, 'utf8');
+    fs.writeFileSync(bumpScriptPath, templateContent);
+  }
+
+  // 3. Update package.json scripts
+  if (!pkg.scripts) pkg.scripts = {};
+  if (!pkg.scripts.bump) {
+    pkg.scripts.bump = 'node scripts/bump.mjs';
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  }
+
+  // 4. Configure Husky if .husky exists
+  const huskyDir = path.join(targetDir, '.husky');
+  if (fs.existsSync(huskyDir)) {
+    const prePushPath = path.join(huskyDir, 'pre-push');
+    const nvmShim = dedent`
+      # NVM Shim (Essential for projects Staff in Linux/NVM)
+      export NVM_DIR="$HOME/.nvm"
+      [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+    `;
+
+    const bumpCmd = '# Pre-push check (non-mutating)\nnpm test';
+
+    if (fs.existsSync(prePushPath)) {
+      const content = fs.readFileSync(prePushPath, 'utf8');
+      if (!content.includes('npm run bump')) {
+        const separator = content.endsWith('\n') ? '' : '\n';
+        fs.appendFileSync(prePushPath, `${separator}\n${nvmShim}\n${bumpCmd}\n`);
+      }
+    } else {
+      const prePushContent = dedent`
+        #!/usr/bin/env sh
+
+        ${nvmShim}
+
+        ${bumpCmd}
+      `;
+      fs.writeFileSync(prePushPath, prePushContent, { mode: 0o755 });
+    }
+  }
+}
+
 const InstructionAssembler = {
   buildMasterInstructions,
   buildClaudeContent,
@@ -536,6 +605,7 @@ const InstructionAssembler = {
   writeBacklogFiles,
   writeGitignore,
   writeManifest,
+  writeAutomationScripts,
 };
 
 export { InstructionAssembler };

package/src/engine/lib/wizard.mjs

@@ -33,7 +33,7 @@ async function gatherUserSelections(targetDir = process.cwd()) {
   let scope = 'fullstack';
   let step = 0;
 
-  const finalStep = () => (selections.mode === 'prompts' ? 2 : 8);
+  const finalStep = () => (selections.mode === 'prompts' ? 2 : 9);
 
   while (step < finalStep()) {
     const context = {
@@ -74,6 +74,7 @@ async function gatherUserSelections(targetDir = process.cwd()) {
     if (stepValue.ide) currentSelections.ide = stepValue.ide;
     if (stepValue.undoLastIdiom) currentSelections.idioms.pop();
     if (stepValue.resetIdioms) currentSelections.idioms = [];
+    if (stepValue.bump !== undefined) currentSelections.bump = stepValue.bump;
     return nextScope;
   }
 }
@@ -98,8 +99,10 @@ async function executeWizardStep(step, context) {
       return promptDesignPreset(context);
     case 7:
       return promptIdeSelection();
+    case 8:
+      return promptBumpAutomation(context);
     default: {
-      const defaultResult = success({ nextStep: 8 });
+      const defaultResult = success({ nextStep: 9 });
       return defaultResult;
     }
   }
@@ -393,6 +396,24 @@ async function promptIdeSelection() {
   return ideResult;
 }
 
+async function promptBumpAutomation(context) {
+  const { selections } = context;
+
+  const hasJsTs = selections.idioms.some((id) => id === 'javascript' || id === 'typescript');
+
+  if (!hasJsTs) {
+    return success({ nextStep: 9, bump: false });
+  }
+
+  const result = await safeConfirm({
+    message: 'Enable automated versioning (Bump & Changelog)?',
+    default: true,
+  });
+
+  const bumpResult = success({ nextStep: 9, bump: result });
+  return bumpResult;
+}
+
 function validateSelections(selections) {
   if (selections.mode === 'quick') {
     selections.flavor = selections.flavor || 'lite';