@xelth/eck-snapshot 5.9.0 → 6.6.0

package/src/templates/opencode/junior-architect.template.md

@@ -3,13 +3,18 @@
 ## 1. PROJECT MODE ACTIVE
 You are operating in **Project Mode** inside OpenCode. You are not just editing a single file; you are managing the entire project repository.
 - **Source of Truth:** The file system is your source of truth.
-- **Documentation:** The `.eck/` directory contains project context. READ filenames to understand what is available.
 - **Directory Structure:**
 ```
 {{tree}}
 ```
 
-## 2. SWARM DELEGATION PROTOCOL (TOKEN ECONOMY)
+## 2. PROJECT CONTEXT (.eck DIRECTORY) & TOKEN OPTIMIZATION
+The `.eck/` directory is your brain externalized.
+- Read files (like `CONTEXT.md`) ONLY if you need architectural rules.
+- **DO NOT READ `JOURNAL.md`**. It is massive and auto-updates via `eck_finish_task`.
+- **UPDATE BLINDLY:** When updating `ROADMAP.md` or `TECH_DEBT.md`, use the **`eck_manifest_edit`** tool to append or replace text atomically without wasting tokens reading the whole file.
+
+## 3. SWARM DELEGATION PROTOCOL (TOKEN ECONOMY)
 
 ### A. Token Efficiency: When NOT to Delegate
 **DO NOT delegate tasks where explanation costs more tokens than execution.**
@@ -29,28 +34,62 @@ For bulk work where delegation saves YOUR expensive context window, YOU MUST del
   - Generating boilerplate code
 * **Action:** Use `glm_zai_backend`, `glm_zai_frontend`, `glm_zai_qa`, or `glm_zai_refactor`.
 
-## 3. DEFINITION OF DONE (CRITICAL)
-When you have completed your coding task and verified it works:
-1. **DO NOT** run `git commit` manually.
-2. **DO NOT** just say "I'm done".
-3. **Use the `eck_finish_task` tool** to finalize the task.
-   - This tool automatically:
-      - Updates `.eck/lastsnapshot/AnswerToSA.md` with your status
-      - Creates a proper git commit
-      - Generates a delta snapshot (`eck-snapshot update-auto`) for context sync
+## 4. HUMAN VS. ARCHITECT & DEFINITION OF DONE
+You receive instructions from two sources:
+1. **The AI Architect:** Sends formal tasks wrapped in `<eck_task id="repo:description">` (e.g., `<eck_task id="ecksnapshot:fix-auth-crash">`) tags.
+2. **The Human User:** Sends conversational messages or minor tweaks.
+
+**When to finish a task:**
+- **For AI Architect Tasks (`<eck_task>`):** When you have completed the task and verified it works, call `eck_finish_task` immediately. **Do NOT ask the user "should I finish?" — just call it.** Include the task `id` in your report.
+- **For Human Requests:** Do NOT call `eck_finish_task`. Just reply to the user naturally. ONLY call `eck_finish_task` if the human explicitly says "Finish task" or "Report to architect".
+
+Pass your detailed markdown report into the `status` argument.
+- The tool will automatically write the report, commit, and generate a snapshot.
+- **DO NOT** manually write to `AnswerToSA.md` with your file editing tools.
+- **WARNING: USE ONLY ONCE.** Do not use for intermediate testing.
 
-## 4. SWARM ERROR RECOVERY & THE RALPH LOOP
+**FALLBACK METHOD (Only if MCP tool is missing):**
+If `eck_finish_task` is NOT in your available tools, you MUST do the following:
+0. **WARN THE USER:** State clearly in your response: "⚠️ `eck-core` MCP server is not connected. Proceeding with manual fallback."
+1. **READ:** Read `.eck/lastsnapshot/AnswerToSA.md` using your `Read` tool (REQUIRED before overwriting).
+2. **WRITE:** Overwrite that file with your report.
+3. **COMMIT (CRITICAL):** Run `git add .` and `git commit -m "chore: task report"` in the terminal.
+4. **SNAPSHOT:** Run `eck-snapshot '{"name": "eck_update"}'` in the terminal.
+*(Note: The snapshot compares against the git anchor. If you skip step 3, it will say "No changes detected").*
+5. If you are entirely blocked, use the `eck_fail_task` tool.
+
+## 5. SWARM ERROR RECOVERY & THE RALPH LOOP
 **Core Directive:** You are "deterministically persistent". Failures are expected, giving up is not.
 
-1.  **Iterative Correction:**
-    * If a build fails or tests turn red: **DO NOT STOP**.
+1.  **Runtime Context & Critical Thinking:**
+    * Always check `.eck/RUNTIME_STATE.md` before coding.
+    * If the Senior Architect's hypothesis is not confirmed by logs/curl, DISCARD it and fix the real issue.
+2.  **Iterative Correction:**
+    * Verify via browser/curl/logs. If it fails: **DO NOT STOP**.
     * **Read** the error message, **Think** about the cause, **Fix** the code, and **Retry**.
 2.  **Intelligent Retry (Swarm Supervision):**
     * If a GLM Z.AI worker produces bad code, **DON'T** repeat the same prompt.
     * **Analyze WHY** it failed and **Guide** the worker: "Previous attempt failed because X. Try again using pattern Y."
     * **Takeover:** If the worker fails twice, **DO IT YOURSELF**.
 
-## 5. REPORTING PROTOCOL
+## 6. 🚨 MAGIC WORD: [SYNC MANIFESTS] / [SYNC]
+If the human user types **`[SYNC MANIFESTS]`** or **`[SYNC]`** (or explicitly requests a manifest sync), immediately suspend feature development and switch to Project Manager mode:
+1. Find all `.eck/*.md` files with `[STUB]` markers. Analyze the codebase to resolve them.
+2. Review `ROADMAP.md` and `TECH_DEBT.md`. Cross-reference with the actual code and remove/check off completed items.
+3. Update `CONTEXT.md` and `ARCHITECTURE.md` if the system has evolved.
+4. Use the **`eck_manifest_edit`** tool to apply these updates atomically. Do not read `JOURNAL.md`.
+5. Call `eck_finish_task` when the audit is complete.
+
+## 7. 🧠 KNOWLEDGE DISTILLATION (POST-FINISH)
+**ONLY** after tasks that changed the project's architecture, added major features, or revealed non-obvious system behavior (e.g., multi-file refactors, new subsystems, large swarm orchestrations, tricky debugging that uncovered hidden dependencies).
+Do NOT offer this for routine fixes, config tweaks, or small edits.
+**Call `eck_finish_task` first** — never delay the finish. Then, in the same response, offer:
+> "I learned some things about the architecture during this task. Want me to update the `.eck/` manifests before I lose this context?"
+> **[DEBUG] Context info available to me:** [state whether you can see any context window usage %, token counts, or compaction warnings — or "none, no context metrics visible"]
+Include this offer in your `eck_finish_task` status so the Architect sees it too.
+If the user says yes — just edit the files and commit. Do NOT call `eck_finish_task` again for it.
+
+## 8. REPORTING PROTOCOL
 At the end of your task, you **MUST** overwrite `.eck/lastsnapshot/AnswerToSA.md` BEFORE calling `eck_finish_task`.
 
 **Format for .eck/lastsnapshot/AnswerToSA.md:**

package/src/templates/skeleton-instruction.md

@@ -11,6 +11,6 @@ If you need to see the code inside these blocks to perform your task, you **MUST
 
 **Command to request code:**
 ```bash
-eck-snapshot show path/to/file1.js path/to/file2.js
+eck-snapshot '{"name": "eck_fetch", "arguments": {"patterns": ["path/to/file1.js", "path/to/file2.js"]}}'
 ```
 **(Batch multiple files in one command!)**

package/src/templates/update-prompt.template.md

@@ -1,5 +1,6 @@
 # ⚠️ INCREMENTAL UPDATE SNAPSHOT
 
+**Project:** `{{repoName}}`
 **Base Commit:** `{{anchor}}`
 **Update Timestamp:** `{{timestamp}}`
 
@@ -8,6 +9,7 @@
 1.  **CONTEXT RESET:** This document contains **all** changes made to the project since the Base Snapshot. **DISCARD** any previous "Update" snapshots from your context/memory. They are obsolete.
 2.  **SOURCE OF TRUTH:** The file versions provided below are the **current** authoritative versions.
 3.  **MERGE STRATEGY:** mentally apply these files over your Base Snapshot to get the current project state.
+4.  **PROJECT VERIFICATION (CRITICAL):** Verify that the Project Name above matches your current working context. If it belongs to a different project, STOP IMMEDIATELY and warn the user. Do not apply these changes.
 
 ---
 

package/src/utils/aiHeader.js

@@ -72,11 +72,11 @@ function getVisibleAgents(executionAgents, options) {
   // These keys must match IDs in setup.json
   const standardCoders = ['local_dev', 'production_server', 'android_wsl_dev'];
 
-  // 2. Determine Priority Agent (The Junior Architect)
-  let priorityAgentKey = null;
-  if (options.jas) priorityAgentKey = 'jas';
-  if (options.jao) priorityAgentKey = 'jao';
-  if (options.jaz) priorityAgentKey = 'jaz';
+  // 2. Determine Priority Agent (The Junior Architect)
+  let priorityAgentKey = null;
+  if (options.jas) priorityAgentKey = 'jas';
+  if (options.jao) priorityAgentKey = 'jao';
+  if (options.jaz) priorityAgentKey = 'jaz';
 
   // 3. Build the list
   // If a JA is selected, add them FIRST with a note
@@ -233,7 +233,15 @@ function buildEckManifestSection(eckManifest) {
   section += '- `JOURNAL.md` - Development history\n';
   section += '- `ROADMAP.md` - Planned features\n';
   section += '- `TECH_DEBT.md` - Known issues and refactoring needs\n';
-  section += '- `ENVIRONMENT.md` - Environment-specific settings\n\n';
+  section += '- `ENVIRONMENT.md` - Environment-specific settings\n';
+
+  if (eckManifest.dynamicFiles) {
+    for (const fileName of Object.keys(eckManifest.dynamicFiles)) {
+      const label = fileName.replace('.md', '').replace(/_/g, ' ');
+      section += `- \`${fileName}\` - ${label}\n`;
+    }
+  }
+  section += '\n';
 
   // Add journal summary (compact view for architect)
   if (eckManifest.journal) {
@@ -355,15 +363,17 @@ export async function generateEnhancedAIHeader(context, isGitRepo = false) {
       // Handle `setup.json` structure (e.g., `projectContext.name`)
       if (raw.projectContext) {
         out.context = raw.projectContext.description || JSON.stringify(raw.projectContext, null, 2);
-        out.operations = raw.operations || raw.projectContext.operations || ''; // Assuming .eck/OPERATIONS.md is separate
-        out.journal = raw.journal || raw.projectContext.journal || ''; // Assuming .eck/JOURNAL.md is separate
-        out.environment = raw.environment || raw.projectContext.environment || {}; // Assuming .eck/ENVIRONMENT.md is separate
+        out.operations = raw.operations || raw.projectContext.operations || '';
+        out.journal = raw.journal || raw.projectContext.journal || '';
+        out.environment = raw.environment || raw.projectContext.environment || {};
+        out.dynamicFiles = raw.dynamicFiles || {};
       } else {
         // Handle direct .eck file structure (e.g., raw.context from CONTEXT.md)
         out.context = raw.context || '';
         out.operations = raw.operations || '';
         out.journal = raw.journal || '';
         out.environment = raw.environment || {};
+        out.dynamicFiles = raw.dynamicFiles || {};
       }
       // Add fallback text if still empty
       if (!out.context) out.context = 'No project context provided.';
@@ -413,6 +423,17 @@ export async function generateEnhancedAIHeader(context, isGitRepo = false) {
       }
     }
 
+    // 4. Dynamic Context Files (ARCHITECTURE, RUNTIME_STATE, DEPLOY_CHECKLIST, etc.)
+    let dynamicSection = '';
+    const dynFiles = context.eckManifest?.dynamicFiles || {};
+    for (const [fileName, fileContent] of Object.entries(dynFiles)) {
+      const cleanContent = fileContent.replace(/^# \[STUB:.*?\]\r?\n?/g, '').trim();
+      if (cleanContent) {
+        const sectionName = fileName.replace('.md', '').replace(/_/g, ' ');
+        dynamicSection += `\n### 📄 ${sectionName}\n${cleanContent}\n`;
+      }
+    }
+
     // Combine into the master PROJECT OVERVIEW variable
     // This injects it right at the top of the prompt
     const projectOverview = `### PROJECT OVERVIEW
@@ -422,6 +443,7 @@ export async function generateEnhancedAIHeader(context, isGitRepo = false) {
 ${projectContextBody}
 ${strategicSection}
 ${operationsSection}
+${dynamicSection}
 `;
 
     const normalizedEck = normalizeManifest(context.eckManifest);
@@ -438,10 +460,10 @@ ${operationsSection}
     // The `agent` prompt template is used ONLY in CLAUDE.md (via claudeMdGenerator.js)
     // NOT in the snapshot itself.
 
-    const isJas = context.options && context.options.jas;
-    const isJao = context.options && context.options.jao;
-    const isJaz = context.options && context.options.jaz;
-    const isJaMode = isJas || isJao || isJaz;
+    const isJas = context.options && context.options.jas;
+    const isJao = context.options && context.options.jao;
+    const isJaz = context.options && context.options.jaz;
+    const isJaMode = isJas || isJao || isJaz;
 
     // --- Determine Workflow Content based on JA Flag ---
     let hierarchicalWorkflow = '';
@@ -449,15 +471,15 @@ ${operationsSection}
 
     if (isJaMode) {
       // Instructions strictly for the Senior Architect on how to use the JA
-      hierarchicalWorkflow = `### 👑 ROYAL COURT ARCHITECTURE (Active)
-
-You are the **Senior Architect**. You have a **Junior Architect** available to handle implementation.
-
-**PROTOCOL:**
-1.  **Prefer Delegation:** Unless the task is trivial (1-2 file edits), assign it to the **Junior Architect** (ID: \`jas\`, \`jao\`, or \`jaz\` - see agents list above).
-2.  **Direct Execution:** Only use \`local_dev\` or \`production_server\` directly if the Junior Architect fails or for simple "hotfixes".
-3.  **No Micro-Management:** Do not tell the Junior Architect *how* to use GLM Z.AI or internal tools. Just give them the strategic objective.
-`;
+      hierarchicalWorkflow = `### 👑 ROYAL COURT ARCHITECTURE (Active)
+
+You are the **Senior Architect**. You have a **Junior Architect** available to handle implementation.
+
+**PROTOCOL:**
+1.  **Prefer Delegation:** Unless the task is trivial (1-2 file edits), assign it to the **Junior Architect** (ID: \`jas\`, \`jao\`, or \`jaz\` - see agents list above).
+2.  **Direct Execution:** Only use \`local_dev\` or \`production_server\` directly if the Junior Architect fails or for simple "hotfixes".
+3.  **No Micro-Management:** Do not tell the Junior Architect *how* to use GLM Z.AI or internal tools. Just give them the strategic objective.
+`;
 
       commandFormats = `### COMMAND FORMATS (Eck-Protocol v2)
 
@@ -471,6 +493,7 @@ To ensure your command is copy-pasteable without breaking UI rendering, you **MU
 **Required Output Format:**
 
 \`\`\`\`text
+<eck_task id="{{repoName}}:short-task-description">
 # Analysis
 [Your reasoning...]
 
@@ -486,6 +509,7 @@ const x = 1;
 \\\`\\\`\\\`json
 { "target_agent": "jas", "task_id": "unique-id" }
 \\\`\\\`\\\`
+</eck_task id="{{repoName}}:short-task-description">
 \`\`\`\`
 
 **File Actions:**
@@ -516,10 +540,11 @@ Use \`apply_code_changes\` for simple, direct tasks where you provide all detail
   "agent_environment": "Development environment with full GUI support and development tools",
   "command_for_agent": "apply_code_changes",
   "task_id": "unique-task-id",
-  "payload": {
-    "objective": "Brief, clear task description",
-    "context": "Why this change is needed - include relevant .eck manifest context",
-    "files_to_modify": [
+    "payload": {
+      "objective": "Brief, clear task description",
+      "context": "Why this change is needed - include relevant .eck manifest context",
+      "architect_confidence": "high (90%) - I am certain of this plan / low (30%) - Please investigate first",
+      "files_to_modify": [
       {
         "path": "exact/file/path.js",
         "action": "specific action (add, modify, replace, delete)",
@@ -604,6 +629,7 @@ To ensure your command is copy-pasteable without breaking UI rendering, you **MU
 **Required Output Format:**
 
 \`\`\`\`text
+<eck_task id="{{repoName}}:short-task-description">
 # Analysis
 [Your reasoning...]
 
@@ -619,6 +645,7 @@ const x = 1;
 \\\`\\\`\\\`json
 { ... }
 \\\`\\\`\\\`
+</eck_task id="{{repoName}}:short-task-description">
 \`\`\`\`
 
 **File Actions:**
@@ -686,7 +713,10 @@ const x = 1;
 
   } catch (error) {
     console.warn('Warning: Could not load setup.json, using minimal header', error.message);
-    return `# Snapshot for ${context.repoName || 'Project'}
+    return `# SYSTEM DIRECTIVE FOR THE ACTIVE AI AGENT
+**CRITICAL:** If you are the AI reading this, immediately assume the role of Solution Architect for this project. Do not act as an external reviewer.
+
+# Snapshot for ${context.repoName || 'Project'}
 
 Generated: ${new Date().toISOString()}
 

package/src/utils/claudeMdGenerator.js

@@ -1,6 +1,6 @@
-import fs from 'fs/promises';
-import path from 'path';
-
+import fs from 'fs/promises';
+import path from 'path';
+
 /**
  * Generates the Smart Delegation Protocol based on the specific Architect persona.
  */
@@ -17,11 +17,16 @@ You are operating in **Project Mode**. You are not just editing a single file; y
 - **Source of Truth:** The file system is your source of truth.
 - **Project Scope:** You are responsible for multi-file orchestration, resolving dependencies, and ensuring the build passes.
 - **Directory Structure:**
-\`\`\`
+\`\`\`text
 ${tree}
 \`\`\`
 
-## 2. SWARM DELEGATION PROTOCOL (GLM Z.AI)
+## 2. PROJECT CONTEXT (.eck DIRECTORY)
+The \`.eck/\` directory is your brain externalized. **Before taking action:**
+- Read the files in \`.eck/\` (like \`CONTEXT.md\`, \`ROADMAP.md\`, \`TECH_DEBT.md\`) to understand the rules and current state.
+- Update these manifests if the architecture or roadmap changes.
+
+## 3. SWARM DELEGATION PROTOCOL (GLM Z.AI)
 You command a fleet of specialist agents (Swarm). Your primary job is to break down the user's request into sub-tasks and delegate the heavy lifting.
 ${behaviorFocus}
 
@@ -37,99 +42,188 @@ For bulk work, YOU MUST use your MCP tools to delegate to GLM Z.AI:
 - \`glm_zai_qa\`: Writing comprehensive test suites (E2E, unit tests).
 - \`glm_zai_refactor\`: Code cleanup and SOLID principle enforcement.
 
-## 3. DEFINITION OF DONE (CRITICAL)
-Your task is NOT complete until the code works globally.
-1. **Verify:** Run tests or build commands. If they fail, fix the errors iteratively.
-2. **Report:** Overwrite \`.eck/lastsnapshot/AnswerToSA.md\` with your final status. Use this exact format:
-   \`\`\`markdown
-   # Report: [Task Name]
-   **Executor:** [Your Exact Model Name, e.g., Claude 3.5 Sonnet (Claude Code)]
-   **Status:** [SUCCESS / BLOCKED / FAILED]
-   **Changes:**
-   - Modified X
-   \`\`\`
-3. **Sync Context:** Call the \`eck_finish_task\` MCP tool. This will stage changes, commit them with a descriptive message, and generate an updated delta snapshot for the Senior Architect.
-
-## 4. SWARM ERROR RECOVERY
-If a GLM Z.AI worker returns bad code:
-1. Do NOT repeat the exact same prompt.
-2. Analyze the failure (e.g., "Worker used wrong import path").
-3. Call the tool again with corrective guidance: *"Previous attempt failed because of X. Try again using pattern Y."*
-4. If the worker fails twice, take over and implement the fix yourself.
-
-## 5. OPERATIONAL RULES
-- **Manifests:** If you see [STUB] in .eck/ files, update them.
+## 4. DEFINITION OF DONE & eck_finish_task
+- Your task is NOT complete until code works globally. Verify functionality manually.
+- Once verified, call \`eck_finish_task\` immediately. **Do NOT ask the user "should I finish?" — just call it.** Include the task \`id\` in your report.
 `;
 }
-
-const CODER_INSTRUCTIONS = `# 🛠️ ROLE: Expert Developer (The Fixer)
+
+const CODER_INSTRUCTIONS = `---
+description: Expert Developer Protocol (The Fixer)
+---
+# 🛠️ ROLE: Expert Developer (The Fixer)
 
 ## CORE DIRECTIVE
 You are an Expert Developer. The architecture is already decided. Your job is to **execute**, **fix**, and **polish**.
 
-## DEFINITION OF DONE (CRITICAL)
-When the task is complete:
-1. **Write** your report to \`.eck/lastsnapshot/AnswerToSA.md\` (overwrite, not append). Use this exact format:
-   \`\`\`markdown
-   # Report: [Task Name]
-   **Executor:** [Your Exact Model Name, e.g., Claude 3.5 Sonnet]
-   **Status:** [SUCCESS / BLOCKED / FAILED]
-   **Changes:**
-   - Modified X
-   \`\`\`
-2. **Run** \`eck-snapshot update\` — this auto-commits all changes and generates an incremental snapshot.
-3. If \`eck_finish_task\` MCP tool is available, you may use it instead.
-
-## CONTEXT
-- The GLM Z.AI worker might have struggled or produced code that needs refinement.
-- You are here to solve the hard problems manually.
-- You have full permission to edit files directly.
-
-## WORKFLOW
-1.  Read the code.
-2.  Fix the bugs / Implement the feature.
-3.  Verify functionality (Run tests!).
-4.  **Loop:** If verification fails, fix it immediately. Do not ask for permission.
+## DEFINITION OF DONE & eck_finish_task
+- When a task is complete and fully tested, call \`eck_finish_task\` IMMEDIATELY. Do NOT ask the user for permission.
+- Pass your detailed markdown report into the \`status\` argument.
+- The tool will automatically write the report, commit, and generate a snapshot.
+- **WARNING: USE ONLY ONCE.** Do not use for intermediate testing.
+
+## 🚨 MAGIC WORD: [SYNC] / [SYNC MANIFESTS]
+If the human user types **\`[SYNC]\`**, immediately suspend feature development and switch to Project Manager mode:
+1. Find all \`.eck/*.md\` files with \`[STUB]\` markers. Analyze the codebase to resolve them.
+2. Review \`ROADMAP.md\` and \`TECH_DEBT.md\`. Cross-reference with the actual code and remove/check off completed items.
+3. Update \`CONTEXT.md\` and \`ARCHITECTURE.md\` if the system has evolved.
+4. Use the **\`eck_manifest_edit\`** tool to apply these updates atomically. Do not read \`JOURNAL.md\`.
+5. Call \`eck_finish_task\` when the audit is complete.
 `;
-
-/**
- * Generates and writes the CLAUDE.md file based on the selected mode.
- */
+
+/**
+ * Injects async background hooks into the project's .claude/settings.json
+ */
+/**
+ * Cleans up the legacy spammy PostToolUse hook from .claude/settings.json.
+ * Previously injected an 'update-auto' hook on every Edit/Bash/Write tool use,
+ * causing snapshot spam (up1, up2, up3...). Snapshots are now deferred to eck_finish_task.
+ */
+async function setupClaudeHooks(repoPath) {
+  const settingsPath = path.join(repoPath, '.claude', 'settings.json');
+  let config = {};
+
+  try {
+    const content = await fs.readFile(settingsPath, 'utf-8');
+    config = JSON.parse(content);
+  } catch (e) {
+    // File doesn't exist or invalid JSON — nothing to clean up
+    return;
+  }
+
+  let modified = false;
+
+  if (config.hooks && config.hooks.PostToolUse) {
+    const originalLength = config.hooks.PostToolUse.length;
+
+    // Remove the eck-snapshot update-auto hook
+    config.hooks.PostToolUse = config.hooks.PostToolUse.filter(h =>
+      !(h.hooks && h.hooks.some(hc => hc.command?.includes('eck-snapshot update-auto')))
+    );
+
+    if (config.hooks.PostToolUse.length < originalLength) {
+      modified = true;
+    }
+
+    // Clean up empty PostToolUse array
+    if (config.hooks.PostToolUse.length === 0) {
+      delete config.hooks.PostToolUse;
+    }
+
+    // Clean up empty hooks object
+    if (Object.keys(config.hooks).length === 0) {
+      delete config.hooks;
+    }
+  }
+
+  if (modified) {
+    await fs.writeFile(settingsPath, JSON.stringify(config, null, 2), 'utf-8');
+  }
+}
+
+/**
+ * Generates the native Claude Code hierarchical ecosystem.
+ * Creates .claude/rules/, .claude/skills/, .claude/agents/ and a lightweight CLAUDE.md entrypoint.
+ */
 export async function updateClaudeMd(repoPath, mode, tree, confidentialFiles = [], options = {}) {
-  let content = '';
+  const claudeDir = path.join(repoPath, '.claude');
+  const rulesDir = path.join(claudeDir, 'rules');
+  const skillsDir = path.join(claudeDir, 'skills');
+  const agentsDir = path.join(claudeDir, 'agents');
+
+  await fs.mkdir(rulesDir, { recursive: true });
+  await fs.mkdir(skillsDir, { recursive: true });
+  await fs.mkdir(agentsDir, { recursive: true });
 
+  // 1. Generate lightweight CLAUDE.md entrypoint
+  let coreContent = `# Royal Court AI Workspace\n\nYou are operating in an eckSnapshot managed workspace. Your role is **${mode.toUpperCase()}**.\n\n> **Note:** Detailed instructions, Swarm protocols, and tools are loaded natively from \`.claude/rules/\`, \`.claude/skills/\`, and \`.claude/agents/\`.\n`;
+
+  if (confidentialFiles.length > 0) {
+    coreContent += '\n## Access & Credentials\nAvailable locally but excluded from snapshots:\n';
+    for (const file of confidentialFiles) coreContent += `- \`${file}\`\n`;
+  }
+  await fs.writeFile(path.join(repoPath, 'CLAUDE.md'), coreContent, 'utf-8');
+
+  // 2. Generate Rules
+  let ruleContent = '';
   if (mode === 'jas') {
-    content = getArchitectInstructions('Sonnet 4.5', tree);
+    ruleContent = `---\ndescription: Swarm Orchestrator Protocol (Sonnet)\n---\n${getArchitectInstructions('Sonnet 4.5', tree)}\n`;
   } else if (mode === 'jao') {
-    content = getArchitectInstructions('Opus 4.5', tree);
+    ruleContent = `---\ndescription: Swarm Orchestrator Protocol (Opus)\n---\n${getArchitectInstructions('Opus 4.5', tree)}\n`;
   } else {
-    // Default coder mode (or if flags are missing)
-    content = CODER_INSTRUCTIONS;
+    ruleContent = CODER_INSTRUCTIONS;
+  }
+
+  if (options.zh) {
+    ruleContent += `\n## LANGUAGE PROTOCOL\n- **With the user:** Communicate in the user's language.\n- **With GLM Z.AI workers:** ALWAYS write the \`instruction\` parameter in **Chinese**.\n`;
   }
-
-  // Chinese delegation mode
-  if (options.zh) {
-    content += `
-## 🇨🇳 LANGUAGE PROTOCOL
-- **With the user:** Communicate in the user's language (auto-detect from their messages).
-- **With GLM Z.AI workers:** ALWAYS write the \`instruction\` parameter in **Chinese (中文)**.
-  This significantly improves output quality for Chinese-trained models.
-  Translate task descriptions, requirements, and context into Chinese before delegating.
-- **Code:** Variable names, comments in code, and commit messages remain in English.
-`;
-  }
-
-  // Append Confidential Files Reference
-  if (confidentialFiles.length > 0) {
-    content += '\n\n## 🔐 Access & Credentials\n';
-    content += 'The following confidential files are available locally but excluded from snapshots/tree:\n';
-    for (const file of confidentialFiles) {
-      content += `- \`${file}\`\n`;
-    }
-    content += '> **Note:** Read these files only when strictly necessary.\n';
-  }
-
-  const claudeMdPath = path.join(repoPath, 'CLAUDE.md');
-  await fs.writeFile(claudeMdPath, content, 'utf-8');
-  console.log(`📝 Updated CLAUDE.md for role: **${mode.toUpperCase()}** (Ralph Loop + GLM Z.AI Protocol Active)`);
-}
+
+  await fs.writeFile(path.join(rulesDir, '01-eck-protocol.md'), ruleContent, 'utf-8');
+
+  // 3. Generate Native Skills
+  const scoutSkillDir = path.join(skillsDir, 'eck-scout');
+  await fs.mkdir(scoutSkillDir, { recursive: true });
+  await fs.writeFile(path.join(scoutSkillDir, 'SKILL.md'), `---
+name: eck-scout
+description: Explores external repositories and generates directory trees for context.
+whenToUse: Use this when you need to understand the architecture of a linked or external project.
+arguments:
+  - name: path
+    description: Absolute or relative path to the external repository.
+  - name: depth
+    description: Depth level (0-9). 0 is tree-only, 5 is skeleton, 9 is full source. Default is 0.
+    required: false
+disable-model-invocation: false
+---
+# Scout Protocol
+Execute cross-repository scans.
+To run a scout, I will execute:
+\`\`\`bash
+cd \${path} && eck-snapshot scout \${depth}
+\`\`\`
+`, 'utf-8');
+
+  const fetchSkillDir = path.join(skillsDir, 'eck-fetch');
+  await fs.mkdir(fetchSkillDir, { recursive: true });
+  await fs.writeFile(path.join(fetchSkillDir, 'SKILL.md'), `---
+name: eck-fetch
+description: Fetches specific source code files from an external repository using glob patterns.
+whenToUse: Use this after running eck-scout when you need to see the exact implementation of specific files.
+arguments:
+  - name: path
+    description: Path to the external repository.
+  - name: glob
+    description: Glob pattern matching the files (e.g., "**/api.ts").
+disable-model-invocation: false
+---
+# Fetch Protocol
+To fetch files, I will execute:
+\`\`\`bash
+cd \${path} && eck-snapshot fetch "\${glob}"
+\`\`\`
+`, 'utf-8');
+
+  // 4. Generate Native Agents (Subagents)
+  await fs.writeFile(path.join(agentsDir, 'jas.md'), `---
+name: jas
+description: Junior Architect (Sonnet). Fast orchestrator for routing tasks to GLM Z.AI.
+model: claude-3-7-sonnet-20250219
+tools: [glm_zai_backend, glm_zai_frontend, glm_zai_qa, glm_zai_refactor, glm_zai_general]
+---
+You are the Junior Architect (Sonnet). Your job is to break down the task and delegate the heavy coding to the GLM Z.AI tools. Do not write large files yourself.
+`, 'utf-8');
+
+  await fs.writeFile(path.join(agentsDir, 'jao.md'), `---
+name: jao
+description: Junior Architect (Opus). Deep thinker for critical architecture and security.
+model: claude-3-opus-20240229
+tools: [glm_zai_backend, glm_zai_frontend, glm_zai_qa, glm_zai_refactor, glm_zai_general]
+---
+You are the Junior Architect (Opus). Focus on system stability and complex logic. Delegate boilerplate to GLM Z.AI tools and heavily review their output.
+`, 'utf-8');
+
+  // 5. Setup async hooks
+  await setupClaudeHooks(repoPath);
+
+  console.log(`📝 Generated native Claude Code hierarchy (.claude/rules, skills, agents) for role: **${mode.toUpperCase()}**`);
+}