@sallmarta/eye-hate-agent 1.0.8 → 1.0.10

package/README.md

@@ -82,10 +82,10 @@ The EHA CLI provides a lightweight, frictionless setup and maintenance toolbelt:
 
 | Command | Primary Purpose |
 | :--- | :--- |
-| `eha init` | Lets you choose your target AI agent, and projects standard rules/skills. |
-| `eha init <agent>` | Directly initiates the EHA project setup for a specific agent (e.g. `copilot`, `claude`, `antigravity`).  |
+| `eha` | **Unified wizard**: banner → agent selection → scope selection (project/device) → install. |
 | `eha doctor` | Performs a health check verifying that all generated files are present and intact. |
-| `eha remove [agent]` | Safely deletes EHA's generated contract files for the specified agent (or all agents if omitted), along with configuration files. |
+| `eha remove [agent]` | Safely deletes EHA's generated project-level contract files for the specified agent (or all agents if omitted), along with configuration files. |
+| `eha uninstall` | Safely deletes EHA's generated device-level contract files from your machine. |
 
 ---
 
@@ -95,22 +95,27 @@ When a new version of EHA is released, simply run:
 ```bash
 $ eha
 ```
-in your repository. The engine will detect the version mismatch automatically, prompt you to regenerate the files **(if needed)**, and update them to the latest standards seamlessly.
+in your repository or from anywhere on your machine. The engine will detect the version mismatch automatically, prompt you to update the files, and update them to the latest standards seamlessly.
 
 ---
 
 ## Uninstallation
 
-To completely remove EHA from your project and device:
+To completely remove EHA:
 
-### 1. Remove project files
-To clean up projected AI files, run the following command in your project root. You can optionally specify a target agent (e.g. `claude`, `copilot`, `antigravity`) to remove only that agent's files while preserving other active installations:
+### 1. Remove project-level (Local) files
+To clean up locally run the following command in your project root. Possible to specify a target agent (e.g. `claude`):
 ```bash
 $ eha remove [agent]
 ```
 
-### 2. Uninstall the CLI globally
-To completely remove the CLI from your device, run:
+### 2. Remove device-level (Global) files
+To clean up globally from your machine, run:
+```bash
+$ eha uninstall
+```
+
+### 3. Remove the CLI Completely
 ```bash
 $ npm uninstall -g @sallmarta/eye-hate-agent
 ```

package/bin/eha.js

@@ -7,57 +7,24 @@ const chalk = require('chalk');
 const readline = require('node:readline/promises');
 const {
   SUPPORTED_AGENT_IDS,
+  deviceManifestExists,
   doctor,
   findRepoRoot,
   initProject,
+  installDevice,
   listSupportedRuntimes,
   listWorkflows,
   readConfig,
+  readDeviceManifest,
   readProjectManifest,
   removeProject,
+  uninstallDevice,
 } = require('../src/engine');
 
 const pkg = require('../package.json');
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-async function promptAgentChoice(currentAgent) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const runtimes = listSupportedRuntimes();
-    const defaultIndex = 1;
-
-    console.log('');
-    console.log('Which agent?');
-    for (let i = 0; i < runtimes.length; i++) {
-      console.log(`  ${i + 1}. ${runtimes[i].name}`);
-    }
-    console.log(`  ${runtimes.length + 1}. All Agents`);
-
-    const maxChoice = runtimes.length + 1;
-    const answer = await rl.question(
-      `Choose [1-${maxChoice}] (default: ${defaultIndex}): `,
-    );
-    const trimmed = answer.trim();
-
-    if (!trimmed) return runtimes[defaultIndex - 1].id;
-
-    const num = parseInt(trimmed, 10);
-    if (num >= 1 && num <= runtimes.length) return runtimes[num - 1].id;
-    if (num === maxChoice) return 'all';
-
-    const normalized = trimmed.toLowerCase();
-    if (normalized === 'all') return 'all';
-
-    const match = runtimes.find(r => r.id === normalized);
-    if (match) return match.id;
-
-    return trimmed.toLowerCase();
-  } finally {
-    rl.close();
-  }
-}
-
 async function promptConfirm(message, defaultYes = false) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -138,116 +105,281 @@ function printDoctorSummary(result) {
   console.log('');
 }
 
-// ─── Wizard (shared by bare invocation and `eha init`) ────────────────────────
+function printBanner() {
+  const ehaRed = chalk.hex('#A61E14').bold;
+  console.log('');
+  console.log(ehaRed('  ███████╗██╗  ██╗ █████╗ '));
+  console.log(ehaRed('  ██╔════╝██║  ██║██╔══██╗'));
+  console.log(ehaRed('  █████╗  ███████║███████║'));
+  console.log(ehaRed('  ██╔══╝  ██╔══██║██╔══██║'));
+  console.log(ehaRed('  ███████╗██║  ██║██║  ██║'));
+  console.log(ehaRed('  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝'));
+  console.log(chalk.gray(`  v${pkg.version}`));
+  console.log('');
+}
 
-async function runInitWizard(agentIdArg) {
-  const rootDir = resolveRootDir();
-  const config = readConfig(rootDir);
-  const manifest = readProjectManifest(rootDir);
+async function checkForUpdates() {
+  try {
+    const https = require('node:https');
+    const data = await new Promise((resolve, reject) => {
+      const req = https.get(
+        'https://registry.npmjs.org/@sallmarta/eye-hate-agent/latest',
+        { timeout: 3000 },
+        (res) => {
+          let body = '';
+          res.on('data', (chunk) => (body += chunk));
+          res.on('end', () => resolve(JSON.parse(body)));
+        },
+      );
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    });
+
+    const latest = data.version;
+    if (latest && latest !== pkg.version) {
+      console.log(
+        chalk.yellow(`  Update available: ${pkg.version} → ${latest}`) +
+        chalk.gray(` — run npm i -g @sallmarta/eye-hate-agent`)
+      );
+      console.log('');
+    }
+  } catch {
+    // Silently ignore — no network, no problem
+  }
+}
 
-  let agentId = agentIdArg ? String(agentIdArg).trim().toLowerCase() : null;
-  const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+function parseAgentInput(input, runtimes) {
+  const trimmed = (input || '').trim();
+  if (!trimmed) return [runtimes[0].id];
+  if (trimmed === '0' || trimmed.toLowerCase() === 'all') return SUPPORTED_AGENT_IDS.slice();
 
-  if (!agentId) {
-    if (isInteractive) {
-      agentId = await promptAgentChoice(config.agent);
+  const parts = trimmed.split(',').map(p => p.trim()).filter(Boolean);
+  const ids = new Set();
+
+  for (const part of parts) {
+    const num = parseInt(part, 10);
+    if (num === 0) return SUPPORTED_AGENT_IDS.slice();
+    if (num >= 1 && num <= runtimes.length) {
+      ids.add(runtimes[num - 1].id);
     } else {
-      agentId = config.agent || SUPPORTED_AGENT_IDS[0];
+      const normalized = part.toLowerCase();
+      if (normalized === 'all') return SUPPORTED_AGENT_IDS.slice();
+      const match = runtimes.find(r => r.id === normalized);
+      if (match) ids.add(match.id);
+      else ids.add(normalized);
     }
   }
 
-  const normalized = String(agentId).trim().toLowerCase();
+  return ids.size > 0 ? [...ids] : [runtimes[0].id];
+}
 
-  if (normalized === 'all') {
-    const installedAgents = config.agents || (config.agent ? [config.agent] : []);
-    if (isInteractive && installedAgents.length > 0) {
-      const listStr = installedAgents.map(a => chalk.cyan(a)).join(', ');
-      const confirm = await promptConfirm(
-        `EHA is set up for: ${listStr}. Overwrite / setup all agents?`,
+async function promptAgentChoice() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const runtimes = listSupportedRuntimes();
+
+    console.log('');
+    console.log('Which agent(s)?');
+    for (let i = 0; i < runtimes.length; i++) {
+      console.log(`  ${i + 1}. ${runtimes[i].name}`);
+    }
+    console.log(`  0. All Agents`);
+
+    const answer = await rl.question(
+      `Choose agent(s) — comma-separate for multiple (e.g. 1,3): `,
+    );
+    return parseAgentInput(answer, runtimes);
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptScope() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log('');
+    console.log('Where should EHA be installed?');
+    console.log(`  1. This project ${chalk.gray('(files in .claude/, .github/, .agents/)')}`);
+    console.log(`  2. Your device — all projects ${chalk.gray('(files in ~/.claude/, ~/.copilot/, ~/.gemini/)')}`);
+
+    const answer = await rl.question(`Choose [1-2]: `);
+    const trimmed = answer.trim();
+
+    if (trimmed === '2' || trimmed.toLowerCase() === 'device' || trimmed.toLowerCase() === 'global') {
+      return 'device';
+    }
+
+    return 'project';
+  } finally {
+    rl.close();
+  }
+}
+
+async function runDeviceInstall(agentIds) {
+  const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+
+  if (isInteractive && deviceManifestExists()) {
+    const manifest = readDeviceManifest();
+    const installedAgentIds = (manifest.agents || []).map(a => a.id);
+    if (installedAgentIds.length > 0) {
+      const listStr = installedAgentIds.map(a => chalk.cyan(a)).join(', ');
+      const ver = manifest.packageVersion || 'unknown';
+      const confirmed = await promptConfirm(
+        `EHA is already installed on your device (${listStr}, v${ver}). Update / overwrite?`,
         true,
       );
-      if (!confirm) {
+      if (!confirmed) {
         console.log('Skipped.');
         return;
       }
     }
+  }
 
-    console.log(chalk.blue('\nInitializing EHA for all agents...'));
-    let fileCount = 0;
-    for (const id of SUPPORTED_AGENT_IDS) {
-      const result = initProject({ rootDir, agentId: id });
-      fileCount += result.fileCount;
-    }
+  console.log('');
+  console.log(chalk.blue('Installing EHA to your device...'));
+  console.log('');
 
+  const result = installDevice({ agentIds });
+
+  const agentNames = { claude: 'Claude', copilot: 'GitHub Copilot', antigravity: 'Antigravity' };
+
+  for (const agentId of result.agentIds) {
+    const agentResult = result.results[agentId];
+    console.log(`  ${chalk.cyan(agentNames[agentId] || agentId)}:`);
+    for (const file of agentResult.files) {
+      const suffix = file.isSentinel ? ` (EHA rules block ${file.action})` : '';
+      console.log(`    ${chalk.green('✓')} ${file.displayPath}${chalk.gray(suffix)}`);
+    }
     console.log('');
-    console.log(chalk.green('✓ EHA is ready for all agents.'));
-    console.log(`  Agents : ${SUPPORTED_AGENT_IDS.map(a => chalk.cyan(a)).join(', ')}`);
-    console.log(`  Files  : ${fileCount} file(s) generated`);
-    console.log('');
-    console.log('Open Agents in this project and run ' + chalk.cyan('/eha-help') + ' to get started or run ' + chalk.cyan('eha doctor') + ' to see all files.');
-    console.log('');
-    return;
   }
 
-  if (!SUPPORTED_AGENT_IDS.includes(normalized)) {
-    const runtimes = listSupportedRuntimes();
-    const list = runtimes.map((r, i) => `${i + 1}. ${r.name}`).join(', ');
+  console.log(chalk.green('✓ EHA installed to your device!'));
+  console.log(`  Open your agent in any project and run ${chalk.cyan('/eha-help')} to get started.`);
+  console.log('');
+}
+
+async function runProjectInstall(agentIds) {
+  const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+
+  let rootDir;
+  try {
+    rootDir = findRepoRoot(process.cwd());
+  } catch {
     console.error(
-      chalk.red(`Unsupported agent: ${agentIdArg || agentId}.`) +
-      ` Choose one of: ${list}, or ${runtimes.length + 1}. All Agents.`,
+      chalk.red('No project root found.') +
+      ' Run ' + chalk.cyan('npm init -y') + ' or ' + chalk.cyan('git init') + ' first.',
     );
     process.exit(1);
   }
-  agentId = normalized;
-
-  const installedAgents = config.agents || (config.agent ? [config.agent] : []);
-  const isAlreadyInstalled = installedAgents.includes(agentId);
-
-  if (isInteractive) {
-    if (isAlreadyInstalled) {
-      const currentVer = manifest.packageVersion || 'unknown';
-      let msg = '';
-      if (currentVer !== pkg.version) {
-        msg = `EHA is already set up for ${chalk.cyan(agentId)} (v${currentVer}). Regenerate with v${pkg.version}?`;
-      } else {
-        msg = `EHA is already set up for ${chalk.cyan(agentId)}. Regenerate/overwrite?`;
-      }
-      const confirm = await promptConfirm(msg, true);
-      if (!confirm) {
-        console.log('Skipped.');
-        return;
-      }
-    } else if (installedAgents.length > 0) {
-      const listStr = installedAgents.map(a => chalk.cyan(a)).join(', ');
-      const confirm = await promptConfirm(
-        `EHA is set up for: ${listStr}. Add ${chalk.cyan(agentId)}?`,
-        true,
-      );
-      if (!confirm) {
-        console.log('Skipped.');
-        return;
-      }
+
+  const config = readConfig(rootDir);
+  const installedAgents = config.agents || [];
+
+  if (isInteractive && installedAgents.length > 0) {
+    const listStr = installedAgents.map(a => chalk.cyan(a)).join(', ');
+    const confirmed = await promptConfirm(
+      `EHA is set up for: ${listStr}. Overwrite / add selected agents?`,
+      true,
+    );
+    if (!confirmed) {
+      console.log('Skipped.');
+      return;
     }
   }
 
-  const result = initProject({ rootDir, agentId });
-  printInitSummary(result);
+  console.log('');
+  console.log(chalk.blue('Installing EHA to this project...'));
+
+  let totalFiles = 0;
+  const allFiles = [];
+  for (const id of agentIds) {
+    const result = initProject({ rootDir, agentId: id });
+    totalFiles += result.fileCount;
+    allFiles.push(...result.files);
+  }
+
+  console.log('');
+  console.log(chalk.green(`✓ EHA is ready.`));
+  console.log(`  Agent${agentIds.length > 1 ? 's' : ''} : ${agentIds.map(a => chalk.cyan(a)).join(', ')}`);
+  console.log(`  Files  : ${totalFiles} file(s) generated`);
+  for (const f of allFiles) {
+    console.log(`    ${chalk.gray(f)}`);
+  }
+  console.log('');
+  console.log(`Open your agent in this project and run ${chalk.cyan('/eha-help')} to get started.`);
+  console.log('');
 }
 
 // ─── CLI definition ────────────────────────────────────────────────────────────
 
 program.name('eha').description('Eye Hate Agent (EHA) — AI workflow toolkit').version(pkg.version);
 
-// Bare `eha` / `eyehateagent` with no subcommand runs the init wizard.
 program.action(async () => {
-  await runInitWizard(null);
+  const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+
+  if (!isInteractive) {
+    program.outputHelp();
+    return;
+  }
+
+  printBanner();
+  await checkForUpdates();
+
+  const agentIds = await promptAgentChoice();
+
+  for (const id of agentIds) {
+    if (!SUPPORTED_AGENT_IDS.includes(id)) {
+      console.error(
+        chalk.red(`Unsupported agent: ${id}.`) +
+        ` Choose from: ${SUPPORTED_AGENT_IDS.join(', ')}`
+      );
+      process.exit(1);
+    }
+  }
+
+  const scope = await promptScope();
+
+  if (scope === 'device') {
+    await runDeviceInstall(agentIds);
+  } else {
+    await runProjectInstall(agentIds);
+  }
 });
 
 program
-  .command('init [agent]')
-  .description(`Set up EHA in this project. Agent: ${SUPPORTED_AGENT_IDS.join(' | ')}`)
+  .command('init [agent]', { hidden: true })
+  .description('(hidden) Project-level install — alias for the unified wizard with scope=project')
   .action(async (agentArg) => {
-    await runInitWizard(agentArg || null);
+    const rootDir = resolveRootDir();
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+
+    let agentIds;
+    if (agentArg) {
+      const normalized = String(agentArg).trim().toLowerCase();
+      agentIds = normalized === 'all' ? SUPPORTED_AGENT_IDS.slice() : [normalized];
+    } else if (isInteractive) {
+      printBanner();
+      agentIds = await promptAgentChoice();
+    } else {
+      agentIds = [SUPPORTED_AGENT_IDS[0]];
+    }
+
+    let totalFiles = 0;
+    const allFiles = [];
+    for (const id of agentIds) {
+      const result = initProject({ rootDir, agentId: id });
+      totalFiles += result.fileCount;
+      allFiles.push(...result.files);
+    }
+
+    console.log('');
+    console.log(chalk.green(`✓ EHA is ready.`));
+    console.log(`  Agent${agentIds.length > 1 ? 's' : ''} : ${agentIds.map(a => chalk.cyan(a)).join(', ')}`);
+    console.log(`  Files  : ${totalFiles} file(s) generated`);
+    for (const f of allFiles) {
+      console.log(`    ${chalk.gray(f)}`);
+    }
+    console.log('');
   });
 
 program
@@ -311,6 +443,37 @@ program
     }
   });
 
+program
+  .command('uninstall')
+  .description('Remove EHA device-level files from your machine')
+  .action(async () => {
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+
+    if (isInteractive) {
+      const confirmed = await promptConfirm(
+        'Remove all device-level EHA files from your machine?',
+      );
+      if (!confirmed) {
+        console.log('Aborted.');
+        return;
+      }
+    }
+
+    const result = uninstallDevice();
+
+    if (result.removedFiles.length === 0) {
+      console.log(chalk.yellow('No device-level EHA installation found.'));
+      return;
+    }
+
+    console.log('');
+    console.log(chalk.green('✓ EHA device-level files removed:'));
+    for (const f of result.removedFiles) {
+      console.log(`  ${chalk.gray(f)}`);
+    }
+    console.log('');
+  });
+
 program
   .command('doctor')
   .description('Show EHA status: config, agent, and generated files')
@@ -319,7 +482,13 @@ program
     printDoctorSummary(doctor({ rootDir }));
   });
 
-program.parseAsync(process.argv).catch((error) => {
-  console.error(chalk.red(error.message));
-  process.exitCode = 1;
-});
+if (require.main === module) {
+  program.parseAsync(process.argv).catch((error) => {
+    console.error(chalk.red(error.message));
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  parseAgentInput,
+};

package/docs/templates/reusable-prompts/00-project-docs-bootstrap.md

@@ -98,21 +98,24 @@ Additionally, ask the user:
 If yes, generate a boilerplate `foundation/changelog.md` with an initial unreleased section.
 
 ### For Brownfield Projects (with existing code):
-Analyze the codebase for active development signals:
-- Recent commits, open branches, TODO comments.
-- Sprint-style branch names (`sprint-*`, `release-*`, `feat/*`).
-- Issue tracker references in commits or code.
-- CI/CD pipeline activity.
-
-If active development signals are found, ask the user:
-"This project appears to be in active development. Would you like to set up phase-based planning to track your development cycles?
+You **MUST** check all four active development signals. Do NOT skip this step:
+
+1. **Recent commits** — run `git log --oneline -20` or equivalent; if there are commits within the last 14 days, OR 10+ commits within the last 30 days, this signal is positive.
+2. **Sprint/feature branches** — run `git branch -a` and look for naming patterns like `sprint/`, `phase/`, `release/`, `feature/`, `feat/`, `dev/`.
+3. **Planning artifacts** — check for `TODO.md`, `ROADMAP.md`, `.github/ISSUE_TEMPLATE/`, issue tracker references in recent commits (e.g., `#123`, `fixes #`, `closes #`), or project board configs.
+4. **TODO density** — grep the codebase for `TODO`, `FIXME`, `HACK` comments; if count ≥ 5, this signal is positive.
+
+If **any one** signal is positive, you **MUST** ask the user:
+"This project shows active development signals ([list which signals were positive and what was found]).
+Would you like to set up `foundation/phases/` to track your development cycles?
 If yes, describe the current and upcoming phases (or I can infer from your codebase)."
 
 If the user provides phases:
 - Create `foundation/phases/index.md` with the phase registry.
 - Create individual phase files using brownfield naming: `phase-P{N}[-description].md` (e.g., `phase-P1-refactor.md`, `phase-P2-auth.md`).
 
-If the user declines or no active development signals: Skip phases entirely.
+If the user declines: Skip phases entirely.
+If all four signals are negative: Skip the phases prompt but note in your output that all four active development signals were negative and no phases were offered.
 
 Additionally, check for release signals (e.g., git tags, version updates in `package.json`, release branches). If found, ask the user:
 "Would you like to set up a changelog (`foundation/changelog.md`) to track historical releases?"
@@ -124,6 +127,7 @@ Before finishing, check that:
 2. `foundation/architecture.md` and `development/testing.md` do not conflict.
 3. The generated documents strictly match the approved Taxonomy Tier, conditional choices, and structural definitions cataloged in the master registry.
 4. If phases were generated, verify `foundation/phases/index.md` correctly registry-links to all individual phase files (`phase-*.md`), and each phase file has complete stable headings.
+5. For brownfield projects: if any active development signal was positive during Step 2.5, confirm that the user was prompted about setting up phases. If this prompt was skipped, **stop and prompt the user now before finishing**.
 
 ## Inputs
 Use the project brief, codebase, and constraints provided below to begin your analysis.

package/docs/templates/reusable-prompts/00-project-docs-refresh.md

@@ -66,11 +66,21 @@ Proceed to the applicable action path.
     - i18n config, locale files → development/internationalization
     - README, inline comments, decision rationale → foundation/prd, architecture
 23. Mark all codebase-inferred facts as `Inferred from codebase` until the user confirms them.
-24. **Active Development & Phases Detection.** When refreshing a project that does not yet have `foundation/phases/`, check for active development signals (recent commits, sprint branches, open milestones, TODO density). If signals are found, prompt the user:
-    "This project appears to be in active development but has no phase-based planning docs.
-    Would you like to set up development phases to track your sprints and milestones?
+24. **Active Development & Phases Detection (MANDATORY).** When refreshing a project that does not yet have `foundation/phases/`, you **MUST** check all four active development signals before proceeding to doc refresh. Do NOT skip this step. The signals are:
+
+    1. **Recent commits** — run `git log --oneline -20` or equivalent; if there are commits within the last 14 days, OR 10+ commits within the last 30 days, this signal is positive.
+    2. **Sprint/feature branches** — run `git branch -a` and look for naming patterns like `sprint/`, `phase/`, `release/`, `feature/`, `feat/`, `dev/`.
+    3. **Planning artifacts** — check for `TODO.md`, `ROADMAP.md`, `.github/ISSUE_TEMPLATE/`, issue tracker references in recent commits (e.g., `#123`, `fixes #`, `closes #`), or project board configs.
+    4. **TODO density** — grep the codebase for `TODO`, `FIXME`, `HACK` comments; if count ≥ 5, this signal is positive.
+
+    If **any one** signal is positive, you **MUST** prompt the user:
+    "This project shows active development signals ([list which signals were positive and what was found]).
+    Would you like to set up `foundation/phases/` to track your development cycles?
     If yes, describe the current and upcoming phases (or I can infer from your codebase)."
+
     If the user agrees, create `foundation/phases/index.md` and individual phase files using brownfield naming (`phase-P{N}[-description].md`, e.g., `phase-P1-refactor.md`).
+    If the user declines, skip phases creation entirely — but still report the detection outcome in the Output Contract.
+    If all four signals are negative, skip the phases prompt but note in your output that all four active development signals were negative and no phases were offered.
 25. **Phases Update Workflow.** When `foundation/phases/` already exists, treat it as a living operational document:
     - Update sprint tracker in the active phase file when sprint-related changes are detected.
     - Mark completed phases by updating their status.
@@ -82,15 +92,16 @@ Proceed to the applicable action path.
 1. Run Step 0 (Doc State Detection).
 2. Read the change summary (if provided) or the user's intent.
 3. **Scan the codebase** — inspect source code, configs, tests, CI/CD pipelines, and package manifests for current truth. This step is NOT optional.
-4. Read the owning project docs (if Active SDD or Mixed state).
-5. Read `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` when present.
-6. Read legacy/reference folders when present.
-7. Read relevant guideline docs when the change touches technical rules.
-8. Identify impacted dependent docs.
-9. Cross-reference codebase findings against doc/legacy claims — resolve conflicts by prompting the user (see rule 21).
-10. Refresh/create the owning docs first (using combined codebase + docs evidence).
-11. Refresh summary or index docs second.
-12. Run a consistency pass.
+4. **Phases Detection Gate** — If `foundation/phases/` does not exist, execute Rule 24 (Active Development & Phases Detection) now. Run all four signal checks using the codebase data from step 3. If any signal is positive, prompt the user about setting up phases before continuing. If `foundation/phases/` already exists, proceed to step 5.
+5. Read the owning project docs (if Active SDD or Mixed state).
+6. Read `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` when present.
+7. Read legacy/reference folders when present.
+8. Read relevant guideline docs when the change touches technical rules.
+9. Identify impacted dependent docs.
+10. Cross-reference codebase findings against doc/legacy claims — resolve conflicts by prompting the user (see rule 21).
+11. Refresh/create the owning docs first (using combined codebase + docs evidence).
+12. Refresh summary or index docs second.
+13. Run a consistency pass.
 
 ## Ownership Examples
 
@@ -122,6 +133,7 @@ Your result should state:
 4. any remaining consistency risks or open questions
 5. which codebase-vs-doc conflicts were resolved and how (per user direction)
 6. the auto-detected tier (for Legacy Only / Non-SDD states), if applicable
+7. whether active development signals were detected, which signals were positive/negative, and whether the user was prompted about `foundation/phases/` setup (include the user's response: accepted, declined, or not yet answered)
 
 ## Final Pass
 
@@ -132,6 +144,7 @@ Before finishing, check that:
 3. no stale summary remains in `foundation/status.md`, `docs/project-docs/index.md`, `technical-guidelines/index.md`, or other index docs
 4. codebase-inferred facts are clearly marked and do not silently override user-confirmed truths
 5. the auto-detected tier (for Legacy Only / Non-SDD states) is stated in the output so the user can override it if needed
+6. if `foundation/phases/` did not exist at the start of this refresh and any active development signal was positive, confirm that the user was prompted about setting up phases — if this prompt was skipped, **stop and prompt the user now before finishing**
 
 ## Inputs
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sallmarta/eye-hate-agent",
-  "version": "1.0.8",
-  "description": "Template-and-engine toolkit for AI-agent-assisted project workflows.",
+  "version": "1.0.10",
+  "description": "A simple Spec-Driven Development (SDD) for AI-agent-assisted project workflows.",
   "directories": {
     "doc": "docs"
   },
@@ -12,7 +12,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "postinstall": "node -e \"try{var c=require('chalk');console.log('\\n'+c.green('✓ EHA installed!')+' Run '+c.cyan('eha')+' to set up.\\n')}catch(e){console.log('\\nEHA installed! Run eha to set up.\\n')}\""
   },
   "keywords": [
     "ai-agent",

package/src/engine/index.js

@@ -1,19 +1,23 @@
 const { getWorkflow, listWorkflows } = require('./workflow-registry');
 const { listSkills } = require('./skill-registry');
-const { findRepoRoot, readConfig } = require('./state');
+const { findRepoRoot, readConfig, deviceManifestExists, readDeviceManifest } = require('./state');
 const { listSupportedRuntimes } = require('./runtime-adapters');
-const { SUPPORTED_AGENT_IDS, doctor, initProject, readProjectManifest, removeProject } = require('./install');
+const { SUPPORTED_AGENT_IDS, doctor, initProject, installDevice, readProjectManifest, removeProject, uninstallDevice } = require('./install');
 
 module.exports = {
   SUPPORTED_AGENT_IDS,
+  deviceManifestExists,
   doctor,
   findRepoRoot,
   getWorkflow,
   initProject,
+  installDevice,
   listSkills,
   listSupportedRuntimes,
   listWorkflows,
   readConfig,
+  readDeviceManifest,
   readProjectManifest,
   removeProject,
+  uninstallDevice,
 };

package/src/engine/install.js

@@ -1,5 +1,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const os = require('node:os');
 const { version: EHA_PACKAGE_VERSION } = require('../../package.json');
 
 const { listWorkflows } = require('./workflow-registry');
@@ -16,6 +17,11 @@ const {
   writeConfig,
   writeJson,
   writeText,
+  getDeviceManifestPath,
+  readDeviceManifest,
+  writeDeviceManifest,
+  upsertSentinelBlock,
+  removeSentinelBlock,
 } = require('./state');
 
 function resolveAgentId(agentId) {
@@ -235,10 +241,165 @@ function readProjectManifest(rootDir) {
   return readManifest(manifestPath);
 }
 
+/**
+ * Install EHA files to the user's device (global/user-level directories).
+ *
+ * @param {Object} options
+ * @param {string[]} options.agentIds - Array of agent IDs to install
+ * @param {string} [options.homeDir] - Override home dir (for testing)
+ * @returns {Object} Result with per-agent file lists and summary
+ */
+function installDevice({ agentIds, homeDir }) {
+  const home = homeDir || os.homedir();
+  const workflows = listWorkflows();
+  const skills = listSkills();
+  const results = {};
+
+  for (const agentId of agentIds) {
+    const normalizedId = resolveAgentId(agentId);
+    const adapter = getRuntimeAdapter(normalizedId);
+
+    if (typeof adapter.generateDeviceFiles !== 'function') {
+      throw new Error(`Agent '${normalizedId}' does not support device-level installation.`);
+    }
+
+    const files = adapter.generateDeviceFiles(home, workflows, skills);
+    const written = [];
+
+    for (const file of files) {
+      if (file.isSentinel) {
+        const action = upsertSentinelBlock(file.absolutePath, file.content);
+        written.push({
+          absolutePath: file.absolutePath,
+          displayPath: file.absolutePath.replace(home, '~'),
+          action,
+          isSentinel: true,
+        });
+      } else {
+        ensureDir(path.dirname(file.absolutePath));
+        writeText(file.absolutePath, file.content);
+        written.push({
+          absolutePath: file.absolutePath,
+          displayPath: file.absolutePath.replace(home, '~'),
+          action: 'written',
+          isSentinel: false,
+        });
+      }
+    }
+
+    results[normalizedId] = {
+      agentId: normalizedId,
+      files: written,
+      fileCount: written.length,
+    };
+  }
+
+  // Write/update device manifest
+  const existingManifest = readDeviceManifest(home);
+  const existingAgents = existingManifest.agents || [];
+
+  const updatedAgents = [...existingAgents];
+  for (const agentId of agentIds) {
+    const normalizedId = resolveAgentId(agentId);
+    const idx = updatedAgents.findIndex(a => a.id === normalizedId);
+    const entry = {
+      id: normalizedId,
+      files: results[normalizedId].files.map(f => f.absolutePath),
+      updatedAt: new Date().toISOString(),
+      packageVersion: EHA_PACKAGE_VERSION,
+    };
+    if (idx !== -1) updatedAgents[idx] = entry;
+    else updatedAgents.push(entry);
+  }
+
+  const allFiles = new Set();
+  for (const agent of updatedAgents) {
+    for (const f of agent.files || []) allFiles.add(f);
+  }
+
+  writeDeviceManifest({
+    manifestVersion: 1,
+    agents: updatedAgents,
+    files: [...allFiles],
+    installedAt: existingManifest.installedAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    packageVersion: EHA_PACKAGE_VERSION,
+  }, home);
+
+  return {
+    homeDir: home,
+    agentIds: agentIds.map(a => resolveAgentId(a)),
+    results,
+    totalFiles: Object.values(results).reduce((sum, r) => sum + r.fileCount, 0),
+  };
+}
+
+/**
+ * Remove EHA device-level files.
+ * If agentId is provided, removes only that agent's files.
+ * If agentId is null, removes all device-level EHA files.
+ */
+function uninstallDevice({ agentId = null, homeDir } = {}) {
+  const home = homeDir || os.homedir();
+  const manifest = readDeviceManifest(home);
+  const removedFiles = [];
+
+  if (!manifest.agents || manifest.agents.length === 0) {
+    return { homeDir: home, removedFiles, message: 'No device-level EHA installation found.' };
+  }
+
+  const agentsToRemove = agentId
+    ? manifest.agents.filter(a => a.id === resolveAgentId(agentId))
+    : manifest.agents;
+
+  for (const agent of agentsToRemove) {
+    for (const filePath of agent.files || []) {
+      const basename = path.basename(filePath);
+      // Sentinel files: GEMINI.md is current; CLAUDE.md is legacy (pre-1.0.10 installs)
+      if (basename === 'CLAUDE.md' || basename === 'GEMINI.md') {
+        const removed = removeSentinelBlock(filePath, home);
+        if (removed) removedFiles.push(filePath.replace(home, '~'));
+      } else {
+        removeFileIfExists(filePath);
+        removeEmptyParents(path.dirname(filePath), home);
+        removedFiles.push(filePath.replace(home, '~'));
+      }
+    }
+  }
+
+  if (agentId) {
+    const remainingAgents = manifest.agents.filter(a => a.id !== resolveAgentId(agentId));
+    if (remainingAgents.length === 0) {
+      removeFileIfExists(getDeviceManifestPath(home));
+      removeEmptyParents(path.dirname(getDeviceManifestPath(home)), home);
+    } else {
+      const allFiles = new Set();
+      for (const a of remainingAgents) {
+        for (const f of a.files || []) allFiles.add(f);
+      }
+      writeDeviceManifest({
+        manifestVersion: 1,
+        agents: remainingAgents,
+        files: [...allFiles],
+        installedAt: manifest.installedAt,
+        updatedAt: new Date().toISOString(),
+        packageVersion: EHA_PACKAGE_VERSION,
+      }, home);
+    }
+  } else {
+    removeFileIfExists(getDeviceManifestPath(home));
+    removeEmptyParents(path.dirname(getDeviceManifestPath(home)), home);
+  }
+
+  return { homeDir: home, removedFiles };
+}
+
 module.exports = {
   SUPPORTED_AGENT_IDS,
   doctor,
   initProject,
+  installDevice,
   readProjectManifest,
   removeProject,
+  uninstallDevice,
 };

package/src/engine/runtime-adapters.js

@@ -200,6 +200,57 @@ When a user asks to run an EHA workflow, use the matching prompt file below.
 ${workflowTable}`;
 }
 
+function buildDeviceRulesContent(agentId, workflows) {
+  const rulesContent = loadRuleContent(agentId);
+
+  let routingSection = '';
+  if (agentId === 'claude') {
+    const routes = workflows
+      .map(w => `- \`${w.commandName}\` → \`~/.claude/commands/eha/eha-${w.commandName}.md\``)
+      .join('\n');
+    routingSection = `\n\n# EHA Workflow Routing\n\nWhen a user asks to run an EHA workflow, use the matching command file:\n\n${routes}`;
+  } else if (agentId === 'antigravity') {
+    const routes = workflows
+      .map(w => `- \`${w.commandName}\` → \`~/.gemini/config/global_workflows/eha-${w.commandName}.md\``)
+      .join('\n');
+    routingSection = `\n\n# EHA Workflow Routing\n\nWhen a user asks to run an EHA workflow, use the matching workflow file:\n\n${routes}`;
+  }
+
+  return `${rulesContent}${routingSection}`;
+}
+
+function buildCopilotDeviceSkillFile(skill) {
+  return `---
+name: "eha-${skill.commandName}"
+description: "EHA skill — ${skill.commandName}"
+---
+
+${EHA_COMPACT_RULES}
+
+---
+
+${loadSkillContent(skill)}`;
+}
+
+function buildCopilotDeviceInstructionsFile(workflows) {
+  const workflowTable = workflows
+    .map(w => `- \`${w.commandName}\` → \`~/.copilot/prompts/eha-${w.commandName}.prompt.md\``)
+    .join('\n');
+
+  return `---
+description: "EHA workflow routing and agent rules for GitHub Copilot"
+applyTo: "**"
+---
+
+${loadRuleContent('copilot')}
+
+# EHA Workflow Routing
+
+When a user asks to run an EHA workflow, use the matching prompt file:
+
+${workflowTable}`;
+}
+
 const RUNTIME_ADAPTERS = {
   claude: {
     id: 'claude',
@@ -225,6 +276,36 @@ const RUNTIME_ADAPTERS = {
         content: buildClaudeRuleFile(),
       });
       
+      return files;
+    },
+    generateDeviceFiles(homeDir, workflows, skills) {
+      const files = [];
+
+      // Commands → ~/.claude/commands/eha/
+      for (const workflow of workflows) {
+        files.push({
+          absolutePath: path.join(homeDir, '.claude', 'commands', 'eha', `eha-${workflow.commandName}.md`),
+          content: buildClaudeCommandFile(workflow),
+          isSentinel: false,
+        });
+      }
+
+      // Skills → ~/.claude/skills/eha-<name>/SKILL.md
+      for (const skill of skills) {
+        files.push({
+          absolutePath: path.join(homeDir, '.claude', 'skills', `eha-${skill.commandName}`, 'SKILL.md'),
+          content: buildClaudeSkillFile(skill),
+          isSentinel: false,
+        });
+      }
+
+      // Rules → ~/.claude/rules/eha-agent-rules.md (own file, not sentinel)
+      files.push({
+        absolutePath: path.join(homeDir, '.claude', 'rules', 'eha-agent-rules.md'),
+        content: buildDeviceRulesContent('claude', workflows),
+        isSentinel: false,
+      });
+
       return files;
     },
   },
@@ -247,7 +328,7 @@ const RUNTIME_ADAPTERS = {
       
       for (const skill of skills) {
         files.push({
-          relativePath: path.join('.github', 'prompts', 'skills', `eha-${skill.commandName}.prompt.md`),
+          relativePath: path.join('.github', 'skills', `eha-${skill.commandName}`, 'SKILL.md'),
           content: buildCopilotSkillFile(skill),
         });
       }
@@ -257,18 +338,48 @@ const RUNTIME_ADAPTERS = {
         content: buildCopilotRuleFile(),
       });
       
+      return files;
+    },
+    generateDeviceFiles(homeDir, workflows, skills) {
+      const files = [];
+
+      // Prompts → ~/.copilot/prompts/eha-<name>.prompt.md
+      for (const workflow of workflows) {
+        files.push({
+          absolutePath: path.join(homeDir, '.copilot', 'prompts', `eha-${workflow.commandName}.prompt.md`),
+          content: buildCopilotPromptFile(workflow),
+          isSentinel: false,
+        });
+      }
+
+      // Skills → ~/.copilot/skills/eha-<name>/SKILL.md
+      for (const skill of skills) {
+        files.push({
+          absolutePath: path.join(homeDir, '.copilot', 'skills', `eha-${skill.commandName}`, 'SKILL.md'),
+          content: buildCopilotDeviceSkillFile(skill),
+          isSentinel: false,
+        });
+      }
+
+      // Instructions → ~/.copilot/instructions/eha.instructions.md (own file, NOT sentinel)
+      files.push({
+        absolutePath: path.join(homeDir, '.copilot', 'instructions', 'eha.instructions.md'),
+        content: buildCopilotDeviceInstructionsFile(workflows),
+        isSentinel: false,
+      });
+
       return files;
     },
   },
   antigravity: {
     id: 'antigravity',
     name: 'Antigravity',
-    description: 'Generates Antigravity-compatible skills in .agents/skills/ and rules in .agents/rules/',
+    description: 'Generates Antigravity-compatible workflows in .agents/workflows/, skills in .agents/skills/, and rules in .agents/rules/',
     generateFiles(rootDir, workflows, skills) {
       const files = [];
       for (const workflow of workflows) {
         files.push({
-          relativePath: path.join('.agents', 'skills', `eha-${workflow.commandName}`, 'SKILL.md'),
+          relativePath: path.join('.agents', 'workflows', `eha-${workflow.commandName}`, 'SKILL.md'),
           content: buildAntigravityCommandFile(workflow),
         });
       }
@@ -284,6 +395,34 @@ const RUNTIME_ADAPTERS = {
         content: buildAntigravityRuleFile(),
       });
       
+      return files;
+    },
+    generateDeviceFiles(homeDir, workflows, skills) {
+      const files = [];
+
+      // Workflows → ~/.gemini/config/global_workflows/eha-<name>.md
+      for (const workflow of workflows) {
+        files.push({
+          absolutePath: path.join(homeDir, '.gemini', 'config', 'global_workflows', `eha-${workflow.commandName}.md`),
+          content: buildAntigravityCommandFile(workflow),
+          isSentinel: false,
+        });
+      }
+      for (const skill of skills) {
+        files.push({
+          absolutePath: path.join(homeDir, '.gemini', 'skills', `eha-${skill.commandName}`, 'SKILL.md'),
+          content: buildAntigravitySkillFile(skill),
+          isSentinel: false,
+        });
+      }
+
+      // Rules → ~/.gemini/GEMINI.md (sentinel block)
+      files.push({
+        absolutePath: path.join(homeDir, '.gemini', 'GEMINI.md'),
+        content: buildDeviceRulesContent('antigravity', workflows),
+        isSentinel: true,
+      });
+
       return files;
     },
   },

package/src/engine/state.js

@@ -1,5 +1,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const os = require('node:os');
 
 const ROOT_MARKERS = ['package.json', '.git'];
 const DEFAULT_CONFIG = {
@@ -122,17 +123,100 @@ function removeEmptyParents(startPath, stopPath) {
   }
 }
 
+const EHA_SENTINEL_START = '<!-- EHA:START — managed by eye-hate-agent, do not edit manually -->';
+const EHA_SENTINEL_END = '<!-- EHA:END -->';
+
+function getDeviceManifestPath(homeDir) {
+  return path.join(homeDir || os.homedir(), '.eha', 'manifest.json');
+}
+
+function readDeviceManifest(homeDir) {
+  const manifestPath = getDeviceManifestPath(homeDir);
+  return readJsonIfExists(manifestPath) || {
+    manifestVersion: 1,
+    agents: [],
+    files: [],
+    installedAt: null,
+    updatedAt: null,
+    packageVersion: null,
+  };
+}
+
+function writeDeviceManifest(manifest, homeDir) {
+  const manifestPath = getDeviceManifestPath(homeDir);
+  writeJson(manifestPath, manifest);
+}
+
+function deviceManifestExists(homeDir) {
+  return fs.existsSync(getDeviceManifestPath(homeDir));
+}
+
+function upsertSentinelBlock(filePath, content) {
+  const block = `${EHA_SENTINEL_START}\n${content}\n${EHA_SENTINEL_END}`;
+
+  if (!fs.existsSync(filePath)) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, block + '\n');
+    return 'created';
+  }
+
+  const existing = fs.readFileSync(filePath, 'utf8');
+  const startIdx = existing.indexOf(EHA_SENTINEL_START);
+  const endIdx = existing.indexOf(EHA_SENTINEL_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = existing.substring(0, startIdx);
+    const after = existing.substring(endIdx + EHA_SENTINEL_END.length);
+    fs.writeFileSync(filePath, before + block + after);
+    return 'updated';
+  }
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(filePath, existing + separator + block + '\n');
+  return 'appended';
+}
+
+function removeSentinelBlock(filePath, stopPath) {
+  if (!fs.existsSync(filePath)) return false;
+
+  const existing = fs.readFileSync(filePath, 'utf8');
+  const startIdx = existing.indexOf(EHA_SENTINEL_START);
+  const endIdx = existing.indexOf(EHA_SENTINEL_END);
+
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return false;
+
+  const before = existing.substring(0, startIdx);
+  const after = existing.substring(endIdx + EHA_SENTINEL_END.length);
+  const result = (before + after).replace(/\n{3,}/g, '\n\n').trim();
+
+  if (!result) {
+    fs.unlinkSync(filePath);
+    removeEmptyParents(path.dirname(filePath), stopPath || os.homedir());
+  } else {
+    fs.writeFileSync(filePath, result + '\n');
+  }
+  return true;
+}
+
 module.exports = {
+  EHA_SENTINEL_START,
+  EHA_SENTINEL_END,
+  deviceManifestExists,
   ensureDir,
   findRepoRoot,
   getBundledAssetPath,
+  getDeviceManifestPath,
   getEnginePaths,
   getPackageRoot,
   readConfig,
+  readDeviceManifest,
   readJsonIfExists,
   removeEmptyParents,
   removeFileIfExists,
+  removeSentinelBlock,
+  upsertSentinelBlock,
   writeConfig,
+  writeDeviceManifest,
   writeJson,
   writeText,
 };