agile-context-engineering 0.2.2 → 0.5.0

package/skills/help/script.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+/**
+ * help skill script — Entry point for all ace-tools operations
+ * needed by the help skill.
+ *
+ * Subcommands:
+ *   init                             Environment detection for help workflow
+ *   ensure-settings                  Create .ace/settings.json with defaults if missing
+ *   setup-github                     Detect gh CLI, repo, and list GitHub Projects
+ *   write-github-settings            Write GitHub Project settings (key=value args)
+ *   sync-agent-teams                 Sync agent_teams from runtime settings to .ace/settings.json
+ *   write-agent-teams <true|false>   Enable/disable agent teams in ACE + runtime settings
+ *   verify-path-exists <path>        Check file/directory existence
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadConfig, pathExists, resolveModel,
+  detectBrownfieldStatus, loadSettings, writeSettings,
+  output, error,
+} = require('../../shared/lib/ace-core');
+
+// ─── Runtime Config Dir ─────────────────────────────────────────────────────
+
+/**
+ * Detect the runtime config directory name.
+ * In the plugin context, the script lives at:
+ *   <base>/<config-dir>/skills/help/script.js
+ * Default to '.claude' since the plugin always runs in Claude Code.
+ */
+function getRuntimeConfigDirName() {
+  try {
+    const skillDir = __dirname;                // <base>/<config-dir>/skills/help
+    const skillsDir = path.dirname(skillDir);  // <base>/<config-dir>/skills
+    const configDir = path.dirname(skillsDir); // <base>/<config-dir>
+    const dirName = path.basename(configDir);
+    if (dirName === '.opencode' || dirName === '.claude') {
+      return dirName;
+    }
+  } catch {}
+  return '.claude';
+}
+
+const RUNTIME_CONFIG_DIR = getRuntimeConfigDirName();
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const raw = args.includes('--raw');
+const cmd = args[0];
+
+switch (cmd) {
+  case 'init':
+    cmdInit(cwd, raw);
+    break;
+  case 'ensure-settings':
+    cmdEnsureSettings(cwd, raw);
+    break;
+  case 'setup-github':
+    cmdSetupGithubProject(cwd, raw);
+    break;
+  case 'write-github-settings':
+    cmdWriteGithubSettings(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'sync-agent-teams':
+    cmdSyncAgentTeams(cwd, raw);
+    break;
+  case 'write-agent-teams':
+    cmdWriteAgentTeamsSetting(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'verify-path-exists': {
+    const targetPath = args[1];
+    if (!targetPath) error('path required for verify-path-exists');
+    const exists = pathExists(cwd, targetPath);
+    output({ exists, path: targetPath }, raw, exists ? 'true' : 'false');
+    break;
+  }
+  default:
+    error(`Unknown command: ${cmd}\nAvailable: init, ensure-settings, setup-github, write-github-settings, sync-agent-teams, write-agent-teams, verify-path-exists`);
+}
+
+// ─── Init: Help ─────────────────────────────────────────────────────────────
+
+/**
+ * Environment detection for the help workflow (project status dashboard).
+ * Detects: git, gh CLI, brownfield status, wiki state, product artifacts.
+ */
+function cmdInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  const result = {
+    // Models (pre-resolved so workflows know which model to spawn each agent with)
+    product_owner_model: resolveModel(cwd, 'ace-product-owner'),
+    researcher_model: resolveModel(cwd, 'ace-project-researcher'),
+    synthesizer_model: resolveModel(cwd, 'ace-research-synthesizer'),
+
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Existing state
+    has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
+    has_system_architecture: pathExists(cwd, '.docs/wiki/system-wide/system-architecture.md'),
+    has_system_structure: pathExists(cwd, '.docs/wiki/system-wide/system-structure.md'),
+    has_coding_standards: pathExists(cwd, '.docs/wiki/system-wide/coding-standards.md'),
+    has_testing_framework: pathExists(cwd, '.docs/wiki/system-wide/testing-framework.md'),
+    project_exists: pathExists(cwd, '.docs/product/product-vision.md'),
+    has_codebase_map: pathExists(cwd, '.ace/codebase'),
+    planning_exists: pathExists(cwd, '.ace'),
+
+    // Brownfield detection
+    ...brownfield,
+    needs_codebase_map: brownfield.is_brownfield && !pathExists(cwd, '.ace/codebase'),
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+
+    // GitHub CLI
+    has_gh_cli: (() => {
+      try {
+        const { execSync } = require('child_process');
+        execSync('gh --version', { stdio: 'pipe' });
+        return true;
+      } catch { return false; }
+    })(),
+  };
+
+  output(result, raw);
+}
+
+// ─── Ensure Settings ────────────────────────────────────────────────────────
+
+function cmdEnsureSettings(cwd, raw) {
+  const settingsPath = path.join(cwd, '.ace', 'settings.json');
+  const alreadyExists = pathExists(cwd, '.ace/settings.json');
+
+  if (!alreadyExists) {
+    const SETTINGS_DEFAULTS = {
+      model_profile: 'balanced',
+      commit_docs: true,
+      agent_teams: false,
+      github_project: {
+        enabled: false,
+        gh_installed: false,
+        repo: '',
+        project_number: null,
+        owner: '',
+      },
+    };
+    const defaults = JSON.parse(JSON.stringify(SETTINGS_DEFAULTS));
+    writeSettings(cwd, defaults);
+    output({ created: true, path: settingsPath, settings: defaults }, raw);
+  } else {
+    const settings = loadSettings(cwd);
+    output({ created: false, path: settingsPath, settings }, raw);
+  }
+}
+
+// ─── Setup GitHub Project ───────────────────────────────────────────────────
+
+function cmdSetupGithubProject(cwd, raw) {
+  const { execSync } = require('child_process');
+  const settings = loadSettings(cwd);
+
+  // Detect gh CLI
+  let ghInstalled = false;
+  try {
+    execSync('gh --version', { stdio: 'pipe' });
+    ghInstalled = true;
+  } catch {}
+
+  // Detect repo
+  let repo = '';
+  let owner = '';
+  if (ghInstalled) {
+    try {
+      repo = execSync('gh repo view --json nameWithOwner -q .nameWithOwner', {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+      }).trim();
+      owner = repo.split('/')[0] || '';
+    } catch {}
+  }
+
+  // List projects
+  let projects = [];
+  if (ghInstalled && owner) {
+    try {
+      const projectsJson = execSync(`gh project list --owner ${owner} --limit 10 --format json`, {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+      }).trim();
+      const parsed = JSON.parse(projectsJson);
+      projects = (parsed.projects || parsed || []).map(p => ({
+        number: p.number,
+        title: p.title,
+      }));
+    } catch {}
+  }
+
+  output({
+    gh_installed: ghInstalled,
+    repo,
+    owner,
+    projects,
+    current_settings: settings.github_project,
+  }, raw);
+}
+
+// ─── Write GitHub Settings ──────────────────────────────────────────────────
+
+function cmdWriteGithubSettings(cwd, raw, extraArgs) {
+  const settings = loadSettings(cwd);
+
+  for (const arg of extraArgs) {
+    const eqIndex = arg.indexOf('=');
+    if (eqIndex === -1) continue;
+    const key = arg.substring(0, eqIndex);
+    const value = arg.substring(eqIndex + 1);
+
+    switch (key) {
+      case 'enabled':
+        settings.github_project.enabled = value === 'true';
+        break;
+      case 'gh_installed':
+        settings.github_project.gh_installed = value === 'true';
+        break;
+      case 'repo':
+        settings.github_project.repo = value;
+        break;
+      case 'project_number':
+        settings.github_project.project_number = value === 'null' ? null : parseInt(value, 10);
+        break;
+      case 'owner':
+        settings.github_project.owner = value;
+        break;
+    }
+  }
+
+  writeSettings(cwd, settings);
+  output({ written: true, settings }, raw);
+}
+
+// ─── Sync Agent Teams ───────────────────────────────────────────────────────
+
+function cmdSyncAgentTeams(cwd, raw) {
+  // Source of truth: runtime settings.json env var (e.g. .claude/settings.json)
+  const claudeSettingsPath = path.join(cwd, RUNTIME_CONFIG_DIR, 'settings.json');
+  let claudeEnabled = false;
+  try {
+    const claudeRaw = fs.readFileSync(claudeSettingsPath, 'utf-8');
+    const claudeSettings = JSON.parse(claudeRaw);
+    const val = claudeSettings?.env?.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    claudeEnabled = val === '1' || val === 'true';
+  } catch {
+    // File doesn't exist or is invalid — treat as disabled
+  }
+
+  // Sync ACE settings to match Claude's source of truth
+  const settings = loadSettings(cwd);
+  const wasDifferent = settings.agent_teams !== claudeEnabled;
+  if (wasDifferent) {
+    settings.agent_teams = claudeEnabled;
+    writeSettings(cwd, settings);
+  }
+
+  output({ agent_teams: claudeEnabled, synced: wasDifferent }, raw);
+}
+
+// ─── Write Agent Teams Setting ──────────────────────────────────────────────
+
+function cmdWriteAgentTeamsSetting(cwd, raw, extraArgs) {
+  const enabled = extraArgs[0] === 'true';
+  const settings = loadSettings(cwd);
+  settings.agent_teams = enabled;
+  writeSettings(cwd, settings);
+
+  // Also update the project's runtime settings.json (e.g. .claude/)
+  const claudeDir = path.join(cwd, RUNTIME_CONFIG_DIR);
+  const claudeSettingsPath = path.join(claudeDir, 'settings.json');
+
+  let claudeSettings = {};
+  try {
+    const existing = fs.readFileSync(claudeSettingsPath, 'utf-8');
+    claudeSettings = JSON.parse(existing);
+  } catch {
+    // File doesn't exist or is invalid — start fresh
+  }
+
+  if (!claudeSettings.env) {
+    claudeSettings.env = {};
+  }
+
+  if (enabled) {
+    claudeSettings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+  } else {
+    delete claudeSettings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    // Clean up empty env object
+    if (Object.keys(claudeSettings.env).length === 0) {
+      delete claudeSettings.env;
+    }
+  }
+
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+  fs.writeFileSync(claudeSettingsPath, JSON.stringify(claudeSettings, null, 2) + '\n', 'utf-8');
+
+  output({ written: true, agent_teams: enabled, settings, claude_settings: claudeSettings }, raw);
+}

package/skills/help/script.test.js

@@ -0,0 +1,183 @@
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SCRIPT = path.join(__dirname, 'script.js');
+
+/**
+ * Create a minimal ACE project structure in a temp directory.
+ */
+function createTestProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+
+  // .ace/config.json
+  const aceDir = path.join(tmpDir, '.ace');
+  fs.mkdirSync(aceDir, { recursive: true });
+  fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+    version: '0.1.0',
+    projectName: 'test-project',
+    model_profile: 'quality',
+    commit_docs: true,
+    github: { enabled: false },
+  }, null, 2));
+
+  // .ace/settings.json
+  fs.writeFileSync(path.join(aceDir, 'settings.json'), JSON.stringify({
+    model_profile: 'quality',
+    commit_docs: true,
+    agent_teams: false,
+    github_project: { enabled: false, gh_installed: false, repo: '', project_number: null, owner: '' },
+  }, null, 2));
+
+  return tmpDir;
+}
+
+function runScript(subcommand, args, cwd) {
+  return execSync(`node "${SCRIPT}" ${subcommand} ${args}`, {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 10000,
+  });
+}
+
+function cleanup(tmpDir) {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('help script', () => {
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns valid JSON with environment detection', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+
+      assert.strictEqual(typeof result.commit_docs, 'boolean');
+      assert.strictEqual(typeof result.has_git, 'boolean');
+      assert.strictEqual(typeof result.has_product_vision, 'boolean');
+      assert.strictEqual(typeof result.has_system_architecture, 'boolean');
+      assert.strictEqual(typeof result.has_system_structure, 'boolean');
+      assert.strictEqual(typeof result.has_coding_standards, 'boolean');
+      assert.strictEqual(typeof result.has_testing_framework, 'boolean');
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.is_greenfield, 'boolean');
+      assert.ok(result.product_owner_model, 'should have product_owner_model');
+    });
+
+    it('detects brownfield vs greenfield correctly', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
+    });
+  });
+
+  describe('ensure-settings', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('reports settings already exist when they do', () => {
+      const result = JSON.parse(runScript('ensure-settings', '', tmpDir));
+      assert.strictEqual(result.created, false);
+      assert.ok(result.settings);
+    });
+
+    it('creates settings when they do not exist', () => {
+      const freshDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+      const aceDir = path.join(freshDir, '.ace');
+      fs.mkdirSync(aceDir, { recursive: true });
+      fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+        version: '0.1.0',
+        projectName: 'test',
+        model_profile: 'balanced',
+        commit_docs: true,
+        github: { enabled: false },
+      }, null, 2));
+
+      const result = JSON.parse(runScript('ensure-settings', '', freshDir));
+      assert.strictEqual(result.created, true);
+      assert.ok(result.settings);
+      assert.strictEqual(result.settings.model_profile, 'balanced');
+
+      cleanup(freshDir);
+    });
+  });
+
+  describe('sync-agent-teams', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns agent_teams boolean', () => {
+      const result = JSON.parse(runScript('sync-agent-teams', '', tmpDir));
+      assert.strictEqual(typeof result.agent_teams, 'boolean');
+      assert.strictEqual(typeof result.synced, 'boolean');
+    });
+  });
+
+  describe('write-agent-teams', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('enables agent teams', () => {
+      const result = JSON.parse(runScript('write-agent-teams', 'true', tmpDir));
+      assert.strictEqual(result.written, true);
+      assert.strictEqual(result.agent_teams, true);
+
+      // Verify .ace/settings.json updated
+      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
+      assert.strictEqual(settings.agent_teams, true);
+    });
+
+    it('disables agent teams', () => {
+      const result = JSON.parse(runScript('write-agent-teams', 'false', tmpDir));
+      assert.strictEqual(result.written, true);
+      assert.strictEqual(result.agent_teams, false);
+
+      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
+      assert.strictEqual(settings.agent_teams, false);
+    });
+  });
+
+  describe('verify-path-exists', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns true for existing path', () => {
+      const result = runScript('verify-path-exists', '.ace/config.json --raw', tmpDir).trim();
+      assert.strictEqual(result, 'true');
+    });
+
+    it('returns false for non-existing path', () => {
+      const result = runScript('verify-path-exists', 'nonexistent/file.md --raw', tmpDir).trim();
+      assert.strictEqual(result, 'false');
+    });
+  });
+
+  describe('error handling', () => {
+    it('errors on unknown command', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+
+    it('errors on verify-path-exists without path', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" verify-path-exists`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+  });
+});

package/{agile-context-engineering/workflows/help.xml → skills/help/workflow.xml}

@@ -22,7 +22,7 @@
 
             <substep order="1.1" name="environment-detection">
                 ```bash
-                INIT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init new-project)
+                INIT=$(node "${CLAUDE_SKILL_DIR}/script.js" init)
                 ```
 
                 <output-fields>
@@ -60,7 +60,7 @@
 
             <substep order="2.1" name="create-settings-file">
                 ```bash
-                SETTINGS=$(node ~/.claude/agile-context-engineering/src/ace-tools.js ensure-settings)
+                SETTINGS=$(node "${CLAUDE_SKILL_DIR}/script.js" ensure-settings)
                 ```
 
                 <output-fields>
@@ -96,7 +96,7 @@
 
             <substep order="3.1" name="github-detection">
                 ```bash
-                GH_STATUS=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init setup-github)
+                GH_STATUS=$(node "${CLAUDE_SKILL_DIR}/script.js" setup-github)
                 ```
 
                 <output-fields>
@@ -218,7 +218,7 @@
 
             <substep order="3.7" name="write-github-settings">
                 ```bash
-                node ~/.claude/agile-context-engineering/src/ace-tools.js write-github-settings enabled=true gh_installed=true repo={repo} project_number={number} owner={owner}
+                node "${CLAUDE_SKILL_DIR}/script.js" write-github-settings enabled=true gh_installed=true repo={repo} project_number={number} owner={owner}
                 ```
 
                 Display:
@@ -245,7 +245,7 @@
                 **MANDATORY — Run this command before evaluating state:**
 
                 ```bash
-                AGENT_TEAMS=$(node ~/.claude/agile-context-engineering/src/ace-tools.js sync-agent-teams --raw)
+                AGENT_TEAMS=$(node "${CLAUDE_SKILL_DIR}/script.js" sync-agent-teams --raw)
                 ```
 
                 Parse the JSON output. The `agent_teams` field is the synced boolean state.
@@ -267,7 +267,7 @@
 
                     <variant condition="user chose Disable">
                         ```bash
-                        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams false
+                        node "${CLAUDE_SKILL_DIR}/script.js" write-agent-teams false
                         ```
                         Display:
                         ```
@@ -286,7 +286,7 @@
 
                     <variant condition="user chose Enable Agent Teams">
                         ```bash
-                        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams true
+                        node "${CLAUDE_SKILL_DIR}/script.js" write-agent-teams true
                         ```
                         Display:
                         ```
@@ -455,7 +455,7 @@
 
             <substep order="9.1" name="check-backlog-exists">
                 ```bash
-                HAS_BACKLOG=$(node ~/.claude/agile-context-engineering/src/ace-tools.js verify-path-exists .ace/artifacts/product/product-backlog.md --raw)
+                HAS_BACKLOG=$(node "${CLAUDE_SKILL_DIR}/script.js" verify-path-exists .ace/artifacts/product/product-backlog.md --raw)
                 ```
 
                 <variant condition="HAS_BACKLOG is true">

package/skills/init-coding-standards/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: init-coding-standards
+description: Generate a tailored coding-standards.md through codebase detection and user interview
+argument-hint: "[optional: context='existing standards doc or notes to build on']"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep, Write, Task, AskUserQuestion
+model: sonnet
+effort: high
+---
+
+# Init Coding Standards
+
+Generate a tailored coding-standards.md through codebase detection and user interview.
+
+## When to Use
+
+- During `/ace:help` — as part of initial project setup
+- After `/ace:map-system` — once codebase is mapped, add prescriptive standards
+- Anytime — to create or refresh coding standards for a project
+- Starting a new project and want to establish coding standards upfront (greenfield or brownfield)
+- Onboarding AI agents to an existing codebase (prevents common AI mistakes)
+- Current coding standards are outdated or missing
+- Team has pain points with AI-generated code quality
+
+## Input
+
+### Optional
+
+- **`context`** — Existing coding standards document, style guide, or notes to use as a starting point. Will be refined through the interview process.
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
+- **Coding standards template**: Read [coding-standards-template.xml](coding-standards-template.xml) — output format for the coding standards
+- **Questioning guide**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml` — deep questioning techniques
+- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` — ACE output formatting rules
+
+## Process
+
+Use the `ace-product-owner` agent for interviewing the user about coding philosophy and pain points.
+
+The Environment Context above contains the preprocessed INIT JSON — use it directly instead of running the init script manually. The workflow's step 1 setup can skip the init bash call since that data is already available.
+
+Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, approvals, commits).
+
+## Artifacts
+
+```
+.docs/wiki/system-wide/coding-standards.md
+```
+
+## Example Usage
+
+```
+# Generate coding standards from codebase analysis + interview
+/ace:init-coding-standards
+
+# Generate with existing standards as seed
+/ace:init-coding-standards context="path/to/existing-style-guide.md"
+```
+
+## Next Steps
+
+- `/ace:map-system` — Map codebase structure and architecture
+- `/ace:help` — Check project initialization status and next steps
+- Review and edit `.docs/wiki/system-wide/coding-standards.md` anytime

package/{agile-context-engineering/templates/wiki/coding-standards.xml → skills/init-coding-standards/coding-standards-template.xml}

@@ -60,6 +60,44 @@
             - **NEVER leave stub implementations** — No `throw NotImplemented`, no `pass`, no `...`
             - If code exists in the codebase, it must be complete and functional
 
+            ### Defensive Programming — Zero Tolerance for Permissive Code
+
+            **WE USE DEFENSIVE PROGRAMMING + FAIL-FAST. PERMISSIVE PROGRAMMING IS BANNED.**
+
+            Permissive programming ("be liberal in what you accept") has caused catastrophic bugs.
+            It hides errors, delays failures, and makes debugging impossible. Every parameter must
+            be validated. Every error must be surfaced. No exceptions.
+
+            **MANDATORY — Do This:**
+            - **Validate EVERY input at the boundary** — check types, ranges, formats, required
+              fields BEFORE processing
+            - **Fail fast and loud** — if something is wrong, return an error immediately with a
+              clear message explaining WHAT is wrong and WHY
+            - **Read the function you're calling** — check its constructor/signature to know EXACTLY
+              what parameters it requires before writing the caller
+            - **Required means required** — if a function needs a value, the caller MUST provide it.
+              No nullable wrappers. No default fallbacks that mask missing data
+            - **Return errors, not defaults** — if a value is missing or invalid, return an error
+              string/throw, do NOT return `""`, `0`, `null`, `[]`, or any placeholder
+            - **Validate on BOTH client and server** — server validates before processing/pushing,
+              client validates as a redundant safety net. Both layers reject garbage
+            - **Surface errors visibly** — errors must reach whoever can fix them (the LLM, the user,
+              the developer). Log them, display them, return them. Never swallow them
+
+            **ABSOLUTELY FORBIDDEN — Never Do This:**
+            - `string? param = null` when the value is actually required — use `string param` and validate
+            - `return ""` or `return null` or `return []` when an operation fails — return an error with context
+            - `.optional()` or `.nullable()` on schema fields that the consuming function REQUIRES
+            - Fallback defaults that hide missing data (e.g., `value ?? defaultValue` to mask a null
+              that should never be null)
+            - `try/catch` that swallows exceptions and returns empty objects
+            - Silently stripping, transforming, or cleaning invalid data to make it pass validation
+            - Writing a caller without reading the callee's actual parameter signature first
+            - Using Postel's Law ("be liberal in what you accept") as justification for accepting garbage
+
+            **The Principle:**
+            **Garbage in → ERROR out. Never garbage in → silence.**
+
             ### No Assumptions
             - **Use LSPs first when available** — Check diagnostics, go-to-definition, and find-references before guessing. The LSP knows the codebase better than a text search.
             - **NEVER assume** libraries, classes, models, methods, or APIs exist