@sallmarta/eye-hate-agent 1.0.6 → 1.0.8

package/README.md

@@ -7,13 +7,14 @@ A simple **Spec-Driven Development (SDD)**. Unified set of rules, specialist ski
 ## Get Started
 
 ### 1. Initialize EHA in your project
-Run directly in **your project root**:
+Run directly in **your project/repo root**:
 ```bash
 $ npx @sallmarta/eye-hate-agent
 ```
 *Or install **globally** and run it:*
 ```bash
 $ npm i -g @sallmarta/eye-hate-agent
+$ cd your-project
 $ eha
 ```
 
@@ -35,6 +36,7 @@ Once initialized, EHA projects a series of interactive workflows directly into y
 | **`/eha-refresh`** | The main workhorse for repos with **any existing documentation**. Updates active SDD docs, migrates legacy docs, converts non-SDD docs, and creates missing SDD files — all by cross-referencing the actual codebase alongside existing material. Auto-detects the appropriate Taxonomy Tier for migration scenarios. Prompts the user to resolve any drift between codebase and docs. |
 | **`/sdd-discuss`** | Collaborative brainstorming. Interviews you about edge cases, API shapes, data models, and constraints, then drafts spec snippets ready for injection into project docs. No code output. |
 | **`/sdd-execute`** | Spec-Driven code generation via strict TDD. Reads specs → generates tests → generates code → validates against architecture. Refuses to code features not in the spec. |
+| **`/eha-help`** | **EHA Help & Tutorial.** Interactive guide providing descriptions of EHA's 4-layer taxonomy, active workflows, and specialist skills. |
 
 > **Looking for parity audits?** Use the `parity-audit` skill directly:
 > `@agent use parity-audit on this repository`
@@ -42,15 +44,47 @@ Once initialized, EHA projects a series of interactive workflows directly into y
 
 ---
 
+## Greenfield vs. Brownfield Workflows
+
+EHA adapts its behavior automatically based on your repository's state:
+
+### Greenfield Projects
+**Start with Discussion:** run
+```bash
+/sdd-discuss
+```
+to brainstorm the tech stack and project specifications, then run 
+```bash
+/eha-bootstrap
+```
+once the discussion is mature.
+
+**Bootstrap Redirect:** If you run `/eha-bootstrap` in a brand-new empty repository, the agent will automatically redirect you to `/sdd-discuss` first.
+
+### Brownfield Projects
+**No Project Docs Yet:** Run 
+```bash
+/eha-bootstrap
+```
+to scan your codebase complexity and generate an appropriate Taxonomy Tier (Lite, Standard, or Enterprise).
+
+**Already Has Project Docs:** Run 
+```bash
+/eha-refresh
+```
+to sync docs with code, migrate legacy folders, and resolve codebase-vs-doc drift with user guidance.
+
+---
+
 ## EHA CLI Command
 
 The EHA CLI provides a lightweight, frictionless setup and maintenance toolbelt:
 
 | Command | Primary Purpose |
 | :--- | :--- |
-| `eha init` (or `npx...`) | Automatically scans your repo root, 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 doctor` | Performs a health check verifying that all projected rules, stubs, and workflows are present and intact. |
+| `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 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. |
 
 ---
@@ -91,4 +125,11 @@ Eye Hate Agent is built upon a core set of operational beliefs designed to optim
 2. **Flexible, Non-Deterministic Context**: EHA documents define clear constraints, design parameters, and business logic (specific) but avoid locking implementation down into rigid boilerplate (generic and non-deterministic). This allows both developers and agents to exercise active engineering judgment and choose the best implementation pathways.
 3. **Zero Agent Hallucination**: By anchoring AI agents to EHA's Single Master Registry catalog (`index.md`) and a strict 4-layer folder structure, EHA eliminates path hallucination, stale references, and prompt redundancy. Agents always know exactly where to read and write.
 4. **Brainstorming & Discussion are Sacred**: Specifications are never written in isolation. EHA integrates a dedicated discuss loop (`02-sdd-discuss.md`), establishing collaborative brainstorming as the mandatory first step to align human intent with agent understanding before any code is generated.
-5. **Native Agile & Scrum Alignment**: EHA is built for real-world software delivery. With structured sprint and epic trackers (`foundation/phases.md`, `foundation/status.md`), EHA fits seamlessly into standard corporate Agile/Scrum lifecycles, enabling agents to act as high-velocity scrum contributors.
+5. **Native Agile & Scrum Alignment**: EHA is built for real-world software delivery. With structured sprint and epic trackers (`foundation/phases/`, `foundation/status.md`), EHA fits seamlessly into standard corporate Agile/Scrum lifecycles, enabling agents to act as high-velocity scrum contributors.
+
+----------
+$$
+SuLyAdeE
+$$
+----------
+

package/bin/eha.js

@@ -25,33 +25,34 @@ async function promptAgentChoice(currentAgent) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
     const runtimes = listSupportedRuntimes();
-    const defaultIndex = currentAgent
-      ? runtimes.findIndex(r => r.id === currentAgent) + 1
-      : 1;
+    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-${runtimes.length}] (default: ${defaultIndex}): `,
+      `Choose [1-${maxChoice}] (default: ${defaultIndex}): `,
     );
     const trimmed = answer.trim();
 
-    // Accept number or name
     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';
 
-    // Fallback: try to match by name (backward compat)
     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(); // Let it fall through
+    return trimmed.toLowerCase();
   } finally {
     rl.close();
   }
@@ -76,11 +77,11 @@ function resolveRootDir() {
   } catch {
     console.error(
       chalk.red('No project root found.') +
-        ' Run ' +
-        chalk.cyan('npm init -y') +
-        ' or ' +
-        chalk.cyan('git init') +
-        ' first.',
+      ' Run ' +
+      chalk.cyan('npm init -y') +
+      ' or ' +
+      chalk.cyan('git init') +
+      ' first.',
     );
     process.exit(1);
   }
@@ -96,15 +97,13 @@ function printInitSummary(result) {
   }
   console.log('');
 
-  if (result.agentId === 'claude') {
-    console.log('Open Claude in this project and run ' + chalk.cyan('/eha-bootstrap') + ' to get started.');
-  } else if (result.agentId === 'copilot') {
-    console.log(
-      'Open GitHub Copilot agent mode and attach ' +
-        chalk.cyan('#eha-bootstrap.prompt.md') +
-        ' to get started.',
-    );
-  }
+  const agentNames = {
+    claude: 'Claude',
+    copilot: 'GitHub Copilot',
+    antigravity: 'Antigravity',
+  };
+  const name = agentNames[result.agentId] || result.agentId;
+  console.log(`Open ${name} in this project and run ${chalk.cyan('/eha-help')} to get started!`);
   console.log('');
 }
 
@@ -158,12 +157,44 @@ async function runInitWizard(agentIdArg) {
   }
 
   const normalized = String(agentId).trim().toLowerCase();
+
+  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?`,
+        true,
+      );
+      if (!confirm) {
+        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.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.error(
       chalk.red(`Unsupported agent: ${agentIdArg || agentId}.`) +
-        ` Choose one of: ${list}.`,
+      ` Choose one of: ${list}, or ${runtimes.length + 1}. All Agents.`,
     );
     process.exit(1);
   }

package/docs/templates/project-docs-template/index.md

@@ -57,8 +57,8 @@ Every project document must include these numbered headings in this exact order.
 | `foundation/architecture.md` | foundation | 1 | System architecture, tech stack, data flow, system flows, ADRs. |
 | `foundation/status.md` | foundation | 1 | High-level status, recent wins, roadmap. |
 | `foundation/workflow.md` | foundation | 1 | Branching, local development loop, PRs, code reviews. |
-| `foundation/phases.md` | foundation | 3 | Overall timelines, features, sub-functions, sprints. (Merged phases + feature inventory) |
-| `foundation/changelog.md` | foundation | 3 | Historical releases log. |
+| `foundation/phases/` | foundation | Conditional | Phase-based project planning. Generated when the project has active development phases (greenfield or brownfield). Contains `index.md` (phase registry) and individual phase files. |
+| `foundation/changelog.md` | foundation | Conditional | Historical releases log. Generated when a project reaches a formal release milestone or requires historical change tracking. |
 | `development/testing.md` | development | 2 | QA policy, matrices, environments, gates, naming standards. |
 | `development/api-contract.md` | development | 2 | API authentication, endpoints, payloads, webhooks, rate limits. |
 | `development/database.md` | development | 2 | Schema, entity models, indexes, migrations, data dictionary. |
@@ -117,13 +117,23 @@ This catalog defines the baseline required domain-specific headings for each doc
 - PR & Code Review
 - Issue Tracking
 
-### `foundation/phases.md`
+### `foundation/phases/index.md`
+- Project Type (Greenfield / Brownfield)
 - Overall Timeline
+- Phase Registry (table of all phases with status, links to individual files)
+- How to Add New Phases
+
+### `foundation/phases/phase-{N}[-description].md` (Greenfield naming)
+### `foundation/phases/phase-P{N}[-description].md` (Brownfield naming)
+- Phase Goal
+- Timeline (Start → End)
 - Feature Summary & Core Functions
-- Sub-Functions
-- Deprecated Features
-- Phase Registry
+- Sub-Functions / Tasks
 - Sprint Tracker
+- Acceptance Criteria
+- Dependencies & Blockers
+- Status (Not Started / In Progress / Complete)
+- Deprecated Features
 
 ### `foundation/changelog.md`
 - [Unreleased] (Added/Changed/Deprecated/Removed/Fixed/Security entries)

package/docs/templates/reusable-prompts/00-eha-help.md

@@ -0,0 +1,56 @@
+---
+description: "EHA workflow - help"
+---
+
+# EHA Help & Tutorial
+
+This is your interactive guide to using Eye Hate Agent (EHA).
+
+## 1. Overview
+Eye Hate Agent (EHA) standardizes human-agent collaboration through a unified Spec-Driven Development (SDD) contract, structured workflows, and specialist skills.
+
+## 2. The 4-Layer Taxonomy
+All project documentation is structured under a predictable 4-layer taxonomy:
+- `docs/project-docs/foundation/` — PRD, Phases, Status, Changelog
+- `docs/project-docs/operations/` — CI/CD, Deployment, Runbooks
+- `docs/project-docs/development/` — Testing, Database, Architecture, API-Contract, UI-UX
+- `docs/project-docs/technical-guidelines/` — Stable project/language/linting guidelines
+
+## 3. Interactive Workflow Commands
+Trigger these commands inside your chat window to coordinate development:
+
+| Trigger Command | Purpose | When to Use |
+| :--- | :--- | :--- |
+| `/eha-bootstrap` | Initializes a brand-new documentation set | Run in repos with **no existing docs**. For truly empty repos, it will guide you to `/eha-discuss` first. |
+| `/eha-refresh` | Synchronizes and migrates project documentation | Run in **active projects** to sync code with docs. |
+| `/sdd-discuss` | Brainstorm specifications and API contracts | Run **before coding** to align specs. |
+| `/sdd-execute` | Spec-driven code generation via TDD | Run **during implementation** to write tests/code. |
+
+## 4. Specialist Skills
+Invoke skills directly in your prompts (e.g. `use eha-api-design`):
+- `eha-system-analysis` — Inspect architecture and codebase logic
+- `eha-api-design` — Plan or refactor REST/GraphQL/gRPC APIs
+- `eha-db-schema-design` — Design schemas and migrations
+- `eha-ui-ux-design` / `eha-wireframing` — UI/UX wireframes and styling systems
+- `eha-code-audit` — Multi-layered verification and codebase scanning
+- `eha-parity-audit` — Automated drift analysis
+- `eha-security-audit` — Dependency scanning and threat modeling
+- `eha-system-tester` — Rigorous testing plans and case design
+- `eha-devops-ci-cd` — Build pipeline configurations
+- `eha-observability` — Logs, metrics, trace instrumentation, and error handling
+- `eha-refactor` — Technical debt cleanup and optimization
+
+## 5. Quick Start Instructions
+If starting a new feature:
+1. Run `/sdd-discuss` to brainstorm specs.
+2. Update project docs to reflect the spec.
+3. Run `/sdd-execute` to execute code via TDD.
+4. Maintain `changelog.md` and `status.md`.
+
+---
+
+## 6. Strict Output Contract (Token Economy)
+When the user triggers this command, you **MUST** adhere to the following rules to conserve maximum tokens:
+1. **Ultra-Concision:** Respond immediately with extremely short, direct answers. Do not write introductory filler (no "Sure, let's look at...", "Here is...", or greetings).
+2. **Minimal Text:** Keep all explanations under 5 words per item. Rely strictly on the tables and bullet lists above.
+3. **Redirection:** Conclude the output in exactly one short question: "Which workflow would you like to run next?"

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

@@ -21,7 +21,32 @@ Bootstrap is for repos with no documentation. For repos with existing docs (even
 
 Should I switch to the Refresh workflow?"
 
-**If NONE exist (only code and/or a bare root README):** Proceed to Step 1.
+**If NONE exist (only code and/or a bare root README):** Proceed to Step 0.5.
+
+## Step 0.5: Greenfield Detection
+
+After passing the Pre-Flight Check, classify the repository:
+
+**Greenfield (Empty/Near-Empty Repo):**
+If the repository has no meaningful source files (only a bare `package.json`, `.gitignore`, or scaffolding from a project generator with no custom code), this is a greenfield project.
+
+STOP. Inform the user:
+
+"This repository appears to be a new/greenfield project with no meaningful codebase yet.
+
+Bootstrap works best when there's code to analyze for complexity detection.
+For a brand-new project, I recommend running `/eha-discuss` first to:
+- Define your project vision, tech stack, and architecture
+- Plan your development phases
+- Draft initial specs
+
+After that, come back to Bootstrap with the discuss output to generate your docs.
+
+Alternatively, if you already know your project's scope, tell me about it and I'll bootstrap directly."
+
+**If the user provides project context directly:** Proceed to Step 1 using the user's description instead of codebase analysis for complexity detection.
+
+**Brownfield with code (normal case):** Proceed to Step 1.
 
 ## Step 1: Complexity Detection (The Adaptive Taxonomy)
 Analyze the workspace to determine its complexity by inspecting the codebase. 
@@ -36,7 +61,9 @@ Based on the repository's complexity, you MUST recommend one of the following **
    - *Files Generated:* Everything in Tier 1 PLUS `development/testing.md`, `development/database.md`, `development/ui-ux.md`, `development/api-contract.md`, `operations/ci-cd.md`.
 3. **Tier 3: Enterprise Profile**
    - *Target:* Large-scale platforms, regulated systems, monorepos.
-   - *Files Generated:* Everything in Tier 2 PLUS `operations/governance.md`, `operations/security-compliance.md` (merged), `operations/observability-error-handling.md` (merged), `operations/production-runbook.md`, `development/internationalization.md`, `foundation/phases.md` (merged phases + feature inventory), `foundation/changelog.md`.
+   - *Files Generated:* Everything in Tier 2 PLUS `operations/governance.md`, `operations/security-compliance.md` (merged), `operations/observability-error-handling.md` (merged), `operations/production-runbook.md`, `development/internationalization.md`.
+
+*Note: `foundation/phases/` (phases folder) and `foundation/changelog.md` (changelog) are offered independently via Step 2.5, not tied to any tier.*
 
 **STOP AND ASK:** Present your analysis of the repo's complexity and ask the user: *"Which Taxonomy Tier should I generate?"* Do not proceed until the user approves a tier.
 
@@ -48,13 +75,55 @@ Once the user approves a tier, strictly follow the 4-layer file structure (`foun
 2. Create project-specific truth in `docs/project-docs/`, not in the reusable prompt output itself.
 3. Do not invent details. Mark uncertain facts as `TBD` or `Assumption`.
 4. If reverse-engineering from code, explicitly state "Inferred from codebase" in the generated document until the user confirms it.
-5. **DO NOT generate files outside the approved tier.**
+5. **DO NOT generate files outside the approved tier unless explicitly chosen during the Step 2.5 conditional interview.**
+
+## Step 2.5: Active Development, Phases, & Changelog Interview
+After generating the tier-selected documents, assess whether the project needs phase-based planning or changelog tracking:
+
+### For Greenfield Projects:
+The project is obviously in active development. Ask the user:
+"This is a new project. Would you like to set up development phases?
+If yes, describe the phases you envision from start to launch.
+Example: Phase 1: Research, Phase 2: API Development, Phase 3: UI/UX, Phase 4: Launch."
+
+If the user provides phases:
+- Create `foundation/phases/index.md` with the phase registry.
+- Create individual phase files using greenfield naming: `phase-{N}[-description].md` (e.g., `phase-1-research.md`, `phase-2-api.md`).
+- Populate each with the user's described scope and `TBD` for details not yet known.
+
+If the user declines: Skip phases entirely.
+
+Additionally, ask the user:
+"Would you like to set up a changelog (`foundation/changelog.md`) to track historical releases?"
+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?
+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.
+
+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?"
+If yes, generate `foundation/changelog.md` populated with current version information.
 
 ## Final Pass
 Before finishing, check that:
 1. No files are generated in the root of `project-docs/` except `index.md` and `getting-started.md`. Everything else must be in its respective subfolder.
 2. `foundation/architecture.md` and `development/testing.md` do not conflict.
-3. The generated documents strictly match the approved Taxonomy Tier and structural definitions cataloged in the master registry.
+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.
 
 ## Inputs
 Use the project brief, codebase, and constraints provided below to begin your analysis.

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

@@ -17,6 +17,8 @@ Before refreshing, classify the repository's documentation state:
 | **Non-SDD Docs** | `docs/` exists with unstructured markdown (no stable headings, no taxonomy) | Conversion refresh: treat as legacy input, create SDD docs from content + codebase |
 | **Mixed** | `docs/project-docs/` exists AND legacy/reference folders also exist | Hybrid refresh: update active SDD docs + migrate unmapped legacy content + codebase |
 
+*Note: For Active SDD and Mixed states, also check for the existence of `foundation/phases/` directory and `foundation/changelog.md` to determine if they need active refreshment.*
+
 For **Legacy Only** and **Non-SDD Docs** states, auto-detect the Taxonomy Tier:
 - Examine the breadth and depth of the existing documentation + codebase complexity.
 - If content covers only core concerns (identity, architecture, status) → Tier 1 (Lite).
@@ -42,10 +44,10 @@ Proceed to the applicable action path.
 9. If the change affects an optional regular doc or its metadata, update `docs/project-docs/index.md` when present.
 10. If the change affects domain-specific technical guidance, update the owning guideline and `technical-guidelines/index.md` when present.
 11. When legacy or reference docs are being mapped into the active owner-doc set, classify them by the durable concern they govern rather than by the legacy folder or filename; legacy names are hints only.
-12. Normalize non-standard legacy labels by meaning when they map cleanly to an active owner. For example, `epic`, `milestone`, or `roadmap` material may map to `docs/project-docs/foundation/phases.md`, while `protocol`, `procedure`, `policy`, or `standard` material may map to `docs/project-docs/technical-guidelines/` when the content is domain-specific technical guidance.
+12. Normalize non-standard legacy labels by meaning when they map cleanly to an active owner. For example, `epic`, `milestone`, or `roadmap` material may map to `docs/project-docs/foundation/phases/`, while `protocol`, `procedure`, `policy`, or `standard` material may map to `docs/project-docs/technical-guidelines/` when the content is domain-specific technical guidance.
 13. When legacy or reference docs show that a justified optional doc should become active under `docs/project-docs/`, promote it into the active owner-doc set instead of leaving it stranded in reference-only folders.
 14. When legacy or reference docs contain domain-specific technical guidance that is still valid, create or update the relevant files under `docs/project-docs/technical-guidelines/` and create `technical-guidelines/index.md` when any guideline becomes active.
-15. When legacy or reference docs contain explicit phased planning, epic tracking, or execution-map detail that should stay active, create or update `docs/project-docs/foundation/phases.md` and register the active optional doc in `docs/project-docs/index.md`.
+15. When legacy or reference docs contain explicit phased planning, epic tracking, or execution-map detail that should stay active, create or update `docs/project-docs/foundation/phases/` and register the active optional doc directory in `docs/project-docs/index.md`.
 16. If a legacy artifact could plausibly map to more than one active owner, or if preserving the legacy label may be intentional, ask the user for direction instead of guessing.
 17. Preserve valuable legacy sections (e.g., 'Decision Rationale') that do not exist in the starter templates. Decide whether this information belongs as a new custom section in an existing document or warrants a new separate file entirely. Ask the user if the best approach is ambiguous. Do not discard domain-specific knowledge just because it lacks a standard template heading.
 18. When asking for that direction, prefer a concise question that states the inferred owner and the fallback choices. Example: `I found legacy "protocol" docs that look like technical guidance. Should I 1. skip them, 2. migrate them into active guideline docs, or 3. preserve "protocol" as a project-specific doc type?`
@@ -64,6 +66,16 @@ 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?
+    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`).
+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.
+    - If the user requests a new phase, create the next numbered phase file and update the index.
+    - Cross-reference `foundation/status.md` epics/roadmap with phase progress.
 
 ### Review Sequence
 
@@ -87,7 +99,7 @@ For each mapping below, also inspect the corresponding codebase artifacts (sourc
 - stack or dependency changes → `foundation/architecture.md`, `development/testing.md`
 - feature scope changes → `foundation/prd.md`, `foundation/status.md`
 - detailed requirements or acceptance changes → `foundation/prd.md`, `foundation/status.md`
-- workflow or roadmap changes → `foundation/status.md`, `foundation/phases.md`, workflow docs if present
+- workflow or roadmap changes → `foundation/status.md`, `foundation/phases/` index/phase files, workflow docs if present
 - validation / CI changes → `development/testing.md`, `getting-started.md`
 - production environment, rollout, rollback, or smoke-check changes → `operations/production-runbook.md`, `foundation/architecture.md`, `development/testing.md`
 - API or integration changes → relevant API / integration docs plus `foundation/architecture.md`
@@ -96,9 +108,9 @@ For each mapping below, also inspect the corresponding codebase artifacts (sourc
 - optional or conditional doc inventory changes → `docs/project-docs/index.md` plus the affected optional owner docs
 - cross-cutting technical conventions or implementation rules → relevant `technical-guidelines/*.md`, `technical-guidelines/index.md`, and any summarizing core docs that reference them
 - documentation-system migration from legacy docs → active owner docs under `docs/project-docs/` first, with `docs-legacy/`, `docs-old/`, or other clearly named archive/reference folders used only as source material
-- semantic legacy-name normalization → map legacy names by content, for example `epic` or `roadmap` material to `foundation/phases.md` and `protocol` or `standard` material to `technical-guidelines/` when their governed concern matches those owners
+- semantic legacy-name normalization → map legacy names by content, for example `epic` or `roadmap` material to `foundation/phases/` and `protocol` or `standard` material to `technical-guidelines/` when their governed concern matches those owners
 - legacy technical-guidance promotion → `docs/project-docs/technical-guidelines/*.md`, `technical-guidelines/index.md`, and any summarizing core docs that now depend on those active guidelines
-- legacy phased-planning promotion → `docs/project-docs/foundation/phases.md`, `foundation/status.md`, and `docs/project-docs/index.md`
+- legacy phased-planning promotion → `docs/project-docs/foundation/phases/`, `foundation/status.md`, and `docs/project-docs/index.md`
 
 ## Output Contract
 

package/docs/templates/rules/agent-rules.md

@@ -32,7 +32,11 @@ Structure incoming requests before acting to reduce rework and catch ambiguity e
   5. Treat a user-provided list as full scope unless the user changes it.
   6. Confirm if the plan could materially change scope, output, or direction.
   7. Then proceed.
-- **3.2** **Lite Mode (Micro-Tasks):** Skip the 7-step intake checklist and SDD requirements ONLY if the user explicitly triggers Lite Mode (e.g., using a `/lite` slash command, or prefixing their request with "Lite task:") AND the task is a trivial, isolated edit (e.g., typo fix, single UI tweak). For Lite Mode, bypass PRD validation and execute immediately to save time.
+- **3.2** **Lite Mode (Micro-Tasks):** Skip the 7-step intake checklist and SDD requirements when the task is a trivial, isolated edit (e.g., typo fix, single UI tweak, comment addition). Lite Mode is triggered by:
+  1. The user prefixing their request with "Lite task:" (e.g., "Lite task: fix the typo in README").
+  2. The agent contextually recognizing an obviously trivial micro-task from the request itself (e.g., "fix that typo", "change the button color to blue").
+  In Lite Mode, bypass PRD validation and the 7-step checklist. Execute immediately.
+  Do NOT apply Lite Mode to tasks that are architectural, multi-file, or scope-changing — even if the user phrases them casually.
 
 ## 4. Docs, Verification, and Completion
 

package/docs/templates/skills/parity-audit/SKILL.md

@@ -98,7 +98,7 @@ Every mismatch should be classified as one of:
 
 When evaluating legacy material, classify it by the durable concern it governs rather than by its legacy name or path. Treat names such as `epic`, `milestone`, `roadmap`, `protocol`, `procedure`, `policy`, or `standard` as hints only.
 
-Report likely mappings when content points to an active owner even if naming differs, such as phased-planning content that should map to `foundation/phases.md` or technical-rule content that should map to `technical-guidelines/`.
+Report likely mappings when content points to an active owner even if naming differs, such as phased-planning content that should map to `foundation/phases/` or technical-rule content that should map to `technical-guidelines/`.
 
 ### Step 4 — Apply structural drift rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sallmarta/eye-hate-agent",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Template-and-engine toolkit for AI-agent-assisted project workflows.",
   "directories": {
     "doc": "docs"

package/src/engine/runtime-adapters.js

@@ -19,7 +19,7 @@ const EHA_COMPACT_RULES = `## EHA Project Doc Rules
 
 **Legacy/Reference Docs:** Treat folders named \`archive/\`, \`docs-legacy/\`, or \`reference/\` as secondary migration input only, never as authoritative active truth.
 
-**Mandatory core docs:** \`index.md\`, \`getting-started.md\`, \`foundation/prd.md\`, \`foundation/architecture.md\`, \`foundation/workflow.md\`, \`foundation/status.md\`, \`foundation/phases.md\`, \`operations/ci-cd.md\`, \`operations/production-runbook.md\`, \`development/testing.md\`, \`development/api-contract.md\`, \`development/database.md\`, \`development/ui-ux.md\`.
+**Mandatory core docs:** \`index.md\`, \`getting-started.md\`, \`foundation/prd.md\`, \`foundation/architecture.md\`, \`foundation/workflow.md\`, \`foundation/status.md\`, \`operations/ci-cd.md\`, \`operations/production-runbook.md\`, \`development/testing.md\`, \`development/api-contract.md\`, \`development/database.md\`, \`development/ui-ux.md\`.
 
 **Authority order:** project docs → codebase → agent judgment. When docs conflict, the owning doc wins. When code and docs conflict and authority is unclear, surface the conflict and ask the user — do not guess.
 
@@ -31,7 +31,7 @@ const EHA_COMPACT_RULES = `## EHA Project Doc Rules
 - Dev loop and PR process → \`foundation/workflow.md\`
 - Verification commands and quality gates → \`development/testing.md\`
 - Execution plan and progress → \`foundation/status.md\`
-- Sprint tracking and backlogs → \`foundation/phases.md\`
+- Sprint tracking and backlogs → \`foundation/phases/\`
 - Optional doc inventory → \`index.md\`
 - Domain-specific technical rules → \`technical-guidelines/\` (Create these only for durable cross-cutting rules; avoid placeholders).
 
@@ -213,11 +213,6 @@ const RUNTIME_ADAPTERS = {
           content: buildClaudeCommandFile(workflow),
         });
       }
-      files.push({
-        relativePath: path.join('.claude', 'commands', 'eha', 'README.md'),
-        content: `# EHA Claude commands\n\nGenerated by \`eha init\`. Use \`/eha-bootstrap\`, \`/eha-refresh\`, \`/sdd-discuss\`, or \`/sdd-execute\` in Claude.\n`,
-      });
-      
       for (const skill of skills) {
         files.push({
           relativePath: path.join('.claude', 'skills', `eha-${skill.commandName}.md`),
@@ -277,11 +272,6 @@ const RUNTIME_ADAPTERS = {
           content: buildAntigravityCommandFile(workflow),
         });
       }
-      files.push({
-        relativePath: path.join('.agents', 'commands', 'eha', 'README.md'),
-        content: `# EHA Antigravity commands\n\nGenerated by \`eha init\`. Call the generated skills directly.\n`,
-      });
-      
       for (const skill of skills) {
         files.push({
           relativePath: path.join('.agents', 'skills', `eha-${skill.commandName}`, 'SKILL.md'),

package/src/engine/workflow-registry.js

@@ -1,6 +1,12 @@
 const path = require('node:path');
 
 const WORKFLOW_DEFINITIONS = {
+  help: {
+    id: 'help',
+    commandName: 'help',
+    description: 'Get help and tutorial on EHA workflows and philosophy',
+    repoRelativePath: path.join('docs', 'templates', 'reusable-prompts', '00-eha-help.md'),
+  },
   bootstrap: {
     id: 'bootstrap',
     commandName: 'bootstrap',