@sallmarta/eye-hate-agent 1.0.2 → 1.0.3

package/.claude/rules/agent-rules.md

@@ -1,64 +0,0 @@
----
-description: "Lean always-on rules for guardrails, context, intake, verification, and doc sync."
-applyTo: "**"
----
-
-# Agent Rules
-
-## 1. Guardrails & Approach
-
-Prevent unilateral changes that could surprise the user and balance proactive execution with alignment.
-
-- **1.1** Ask before making material architecture, naming, or tool changes. Skip this for micro-decisions.
-- **1.2** Balance proactive execution with user alignment so initiative never outpaces agreement.
-- **1.3** If a better approach exists, compare the user's apparent expectation with the recommended path clearly and briefly. Use a short table when that sharpens the tradeoff. Phrasing to use: *"I have an alternative approach that may be better - want me to use it instead?"*
-
-## 2. Context & Cache Integrity
-
-Protect the prompt prefix cache and manage context-window capacity to preserve the 90% cached-token discount.
-
-- **2.1** Keep always-on context small. Keep rules generic and leave project-specific facts in project docs under `docs/project-docs/`.
-- **2.2** Read the smallest owning doc that resolves the decision rather than scanning the entire repository.
-- **2.3** **Prefix & Lookback Integrity (Claude):** Cache reads cost 90% less but require a byte-identical prefix in tools -> system -> messages order. Never reorder, add, or remove tool definitions mid-session. Never inject dynamic content (timestamps, per-request IDs) into the system prompt — move it to a late user message instead.
-- **2.4** **Claude Cache Breakpoints:** In heavy agentic loops, be aware of the ~20-block lookback window. If a single turn produces more than ~15 tool-use/tool-result pairs, explicitly request the user to perform a minor conversational interaction or place a cache breakpoint block to prevent silent cache misses on subsequent turns.
-- **2.5** **Session Continuity (No Dynamic Compaction):** Never modify, compact, or delete prior chat turns mid-session—this destroys the hardware prefix cache. If context reaches ~65% capacity, compile a comprehensive session-handoff.md to `active-repo/memories/session/session-handoff.md` (overwriting any previous handoff, and ensure `active-repo/memories/session/` is added to `.gitignore` if created). The handoff must contain a full, detailed summary of the active conversation's progress, decisions, and open threads, strictly redact all sensitive information (such as API keys, passwords, credentials, or PII), and incorporate any user-provided compaction arguments as next-session focus areas. Prompt the user to run `/clear` or open a new session with this file loaded, providing a copy-pasteable short prompt (e.g., "Resume session from memories/session/session-handoff.md") to load the handoff instantly.
-
-## 3. Intake & Scope Alignment
-
-Structure incoming requests before acting to reduce rework and catch ambiguity early.
-
-- **3.1** For non-trivial tasks, follow this 7-step checklist before coding:
-  1. Summarize the request in 1–3 sentences.
-  2. Analyze before implementing. Brainstorm when the task benefits from options, tradeoffs, or sequencing.
-  3. Ask clarifying questions when the request is ambiguous, under-specified, expectations are misplaced, or confidence is below 95%. **Clarify scope or output format before execution, not at completion.**
-  4. Make a short ordered plan or todo list.
-  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** Skip the intake checklist only for trivial single-step edits.
-
-## 4. Docs, Verification, and Completion
-
-Ensure every task ends with verified output, synchronized documentation, and clear follow-ups.
-
-- **4.1** State a point once, in its strongest owning section.
-- **4.2** Default live response shape when no stronger format applies: Summary -> What I'll Do -> Result or Next Action -> Validation or Limitation -> Optional Follow-Up.
-- **4.3** Stronger formats win: user formatting requests > mode-specific files > skill or prompt `Output Contract`.
-- **4.4** **Knowledge & Memory Preservation:** Preserve unique information when writing to memory. If valuable legacy or codebase knowledge does not fit standard headings, decide: new section, new file, or ask the user if the best location is ambiguous.
-- **4.5** **Documentation Sync:** After code or rule changes, sync affected docs under `docs/project-docs/` to ensure they remain the canonical source of truth.
-- **4.6** **Follow-Up Suggestions:** After completing a task, you may suggest 1–3 high-value, optional next actions. Never apply them silently. Phrasing: *"Task complete. Noticed X could be improved - want me to handle that too? or I can explain it if you want to review first."*
-
-## 5. Contract Essentials
-
-Embed the critical behavioral rules from the contract so agents follow them without opening the full contract on every task.
-
-- **5.1 Skills & Relevance:** Treat attached or mentioned skills as relevance hints, not automatic requirements. If a skill is clearly unnecessary, say so briefly and proceed directly unless the user insists. Prefer the single most relevant skill over chaining multiple.
-- **5.2 Decision Precedence:** Resolve routing, conflict, and behavior decisions in this strict order:
-  1. User's requested goal and output.
-  2. User's explicit constraints or preferences.
-  3. The active contract (`docs/eyehateagent-contract.md`) and the owning project docs under `docs/project-docs/`.
-  4. Attached context (skills, notes, or examples) treated as relevance hints unless made mandatory.
-  5. Automatic agent judgment.
-- **5.3 Failure & Fallback:** If a required project doc is missing, note the gap and create the smallest owning doc that unblocks the task. If code, tests, configs, or runtime-facing artifacts conflict with active docs and authority is unclear, do not guess: surface the conflict, cite the evidence, and ask the user before choosing the fix path.
-- **5.4 Codebase & Comment Integrity:** Maintain absolute documentation and codebase integrity when making modifications. Preserve all existing comments, docstrings, formatting, and structures that are unrelated to your changes unless explicitly instructed otherwise. Never delete unrelated comments or placeholder code silently.
-- **5.5 Completion & Verification:** End each task with the requested output and the narrowest applicable validation from `docs/project-docs/testing.md` (or a structural review with an explicit limitation if no executable check exists). Re-read output for correctness, edge cases, and unexpected side effects before finishing. Include a doc-sync check when ownership changed.

package/.github/instructions/agent-rules.instructions.md

@@ -1,63 +0,0 @@
----
-description: "Lean always-on rules for guardrails, context, intake, verification, and doc sync."
-applyTo: "**"
----
-
-# Agent Rules
-
-## 1. Guardrails & Approach
-
-Prevent unilateral changes that could surprise the user and balance proactive execution with alignment.
-
-- **1.1** Ask before making material architecture, naming, or tool changes. Skip this for micro-decisions.
-- **1.2** Balance proactive execution with user alignment so initiative never outpaces agreement.
-- **1.3** If a better approach exists, compare the user's apparent expectation with the recommended path clearly and briefly. Use a short table when that sharpens the tradeoff. Phrasing to use: *"I have an alternative approach that may be better - want me to use it instead?"*
-
-## 2. Context & Cache Integrity
-
-Protect the prompt prefix cache and manage context-window capacity to preserve the 90% cached-token discount.
-
-- **2.1** Keep always-on context small. Keep rules generic and leave project-specific facts in project docs under `docs/project-docs/`.
-- **2.2** Read the smallest owning doc that resolves the decision rather than scanning the entire repository.
-- **2.3** **Context Efficiency (Copilot):** Under usage-based billing, cached tokens still cost AI Credits — keep instruction files and session context lean rather than exhaustive. Prefer explicit context (`#file`, `#selection`) over broad implicit context. Start a fresh session or use `/clear` when switching to an unrelated task to prevent context clutter from degrading cache-hit quality. Do not accumulate stale file references or conversation history that is no longer relevant to the active task.
-- **2.4** **Session Continuity (No Dynamic Compaction):** Never modify, compact, or delete prior chat turns mid-session—this destroys the hardware prefix cache. If context reaches ~65% capacity, compile a comprehensive session-handoff.md to `active-repo/memories/session/session-handoff.md` (overwriting any previous handoff, and ensure `active-repo/memories/session/` is added to `.gitignore` if created). The handoff must contain a full, detailed summary of the active conversation's progress, decisions, and open threads, strictly redact all sensitive information (such as API keys, passwords, credentials, or PII), and incorporate any user-provided compaction arguments as next-session focus areas. Prompt the user to run `/clear` or open a new session with this file loaded, providing a copy-pasteable short prompt (e.g., "Resume session from memories/session/session-handoff.md") to load the handoff instantly.
-
-## 3. Intake & Scope Alignment
-
-Structure incoming requests before acting to reduce rework and catch ambiguity early.
-
-- **3.1** For non-trivial tasks, follow this 7-step checklist before coding:
-  1. Summarize the request in 1–3 sentences.
-  2. Analyze before implementing. Brainstorm when the task benefits from options, tradeoffs, or sequencing.
-  3. Ask clarifying questions when the request is ambiguous, under-specified, expectations are misplaced, or confidence is below 95%. **Clarify scope or output format before execution, not at completion.**
-  4. Make a short ordered plan or todo list.
-  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** Skip the intake checklist only for trivial single-step edits.
-
-## 4. Docs, Verification, and Completion
-
-Ensure every task ends with verified output, synchronized documentation, and clear follow-ups.
-
-- **4.1** State a point once, in its strongest owning section.
-- **4.2** Default live response shape when no stronger format applies: Summary -> What I'll Do -> Result or Next Action -> Validation or Limitation -> Optional Follow-Up.
-- **4.3** Stronger formats win: user formatting requests > mode-specific files > skill or prompt `Output Contract`.
-- **4.4** **Knowledge & Memory Preservation:** Preserve unique information when writing to memory. If valuable legacy or codebase knowledge does not fit standard headings, decide: new section, new file, or ask the user if the best location is ambiguous.
-- **4.5** **Documentation Sync:** After code or rule changes, sync affected docs under `docs/project-docs/` to ensure they remain the canonical source of truth.
-- **4.6** **Follow-Up Suggestions:** After completing a task, you may suggest 1–3 high-value, optional next actions. Never apply them silently. Phrasing: *"Task complete. Noticed X could be improved - want me to handle that too? or I can explain it if you want to review first."*
-
-## 5. Contract Essentials
-
-Embed the critical behavioral rules from the contract so agents follow them without opening the full contract on every task.
-
-- **5.1 Skills & Relevance:** Treat attached or mentioned skills as relevance hints, not automatic requirements. If a skill is clearly unnecessary, say so briefly and proceed directly unless the user insists. Prefer the single most relevant skill over chaining multiple.
-- **5.2 Decision Precedence:** Resolve routing, conflict, and behavior decisions in this strict order:
-  1. User's requested goal and output.
-  2. User's explicit constraints or preferences.
-  3. The active contract (`docs/eyehateagent-contract.md`) and the owning project docs under `docs/project-docs/`.
-  4. Attached context (skills, notes, or examples) treated as relevance hints unless made mandatory.
-  5. Automatic agent judgment.
-- **5.3 Failure & Fallback:** If a required project doc is missing, note the gap and create the smallest owning doc that unblocks the task. If code, tests, configs, or runtime-facing artifacts conflict with active docs and authority is unclear, do not guess: surface the conflict, cite the evidence, and ask the user before choosing the fix path.
-- **5.4 Codebase & Comment Integrity:** Maintain absolute documentation and codebase integrity when making modifications. Preserve all existing comments, docstrings, formatting, and structures that are unrelated to your changes unless explicitly instructed otherwise. Never delete unrelated comments or placeholder code silently.
-- **5.5 Completion & Verification:** End each task with the requested output and the narrowest applicable validation from `docs/project-docs/testing.md` (or a structural review with an explicit limitation if no executable check exists). Re-read output for correctness, edge cases, and unexpected side effects before finishing. Include a doc-sync check when ownership changed.

package/.github/instructions/eha-workflows.instructions.md

@@ -1,21 +0,0 @@
----
-description: "Generated EHA workflow routing for GitHub Copilot"
-applyTo: "**"
----
-
-# EHA Engine Workflows
-
-When a user asks to run an EHA workflow, prefer the canonical reusable prompt file listed below and preserve its output contract.
-
-- `bootstrap` -> `docs/vibes/reusable-prompts/00-project-docs-bootstrap.md`
-- `refresh` -> `docs/vibes/reusable-prompts/00-project-docs-refresh.md`
-- `parity` -> `docs/vibes/reusable-prompts/00-project-docs-parity.md`
-- `discuss` -> `docs/vibes/reusable-prompts/02-sdd-discuss.md`
-- `execute` -> `docs/vibes/reusable-prompts/01-sdd-execute.md`
-- `verify` -> `docs/vibes/reusable-prompts/00-project-docs-parity.md` (A dedicated verify workflow does not exist yet; verify currently routes to the parity workflow.)
-
-## Runtime support
-
-- GitHub Copilot support tier is **guided**
-- this install generates repo-local instructions, not slash commands
-- generated outputs stay inside the repository for transparency

package/docs/eyehateagent-contract.md

@@ -1,475 +0,0 @@
-# Project Documentation Contract
-
-## Purpose
-
-This document defines the **canonical project-doc contract** for repositories that use this template.
-
-Its job is to keep three layers aligned:
-
-1. **Instructions / rules** stay generic and reusable.
-2. **Skills** stay procedural and reusable.
-3. **Project docs** hold the project-specific truth about stack, commands, architecture, testing, workflow, and scope.
-
-If a repository changes stacks, runtime models, or framework choices, the required adjustment should happen primarily in the owning project docs under `docs/project-docs/` rather than by rewriting the core rules or skills.
-
----
-
-## Operating Model
-
-### Rules and instructions
-
-- Rules enforce behavior, guardrails, and quality expectations.
-- Rules must **not** hardcode stack-specific commands or framework assumptions when that information belongs in project docs.
-- This repository intentionally keeps the context-compaction trigger of roughly 65% in the platform instruction surfaces (mirrored rule files) as an agent-operating threshold. Treat it as a deliberate exception to the general preference for principle-based reusable rules.
-- Rules should read the relevant files in `docs/project-docs/` directly.
-
-### Skills
-
-- Skills define reusable expert-role procedures such as testing, analysis, API design, auditing, or documentation refresh.
-- Skills should begin by reading the relevant project docs before applying their reusable expert procedure.
-- Skills may include examples, but examples must not become hidden project-specific requirements.
-
-### Reusable prompts
-
-- In this repository, `prompt` means the user's live request.
-- `Reusable prompt` means a reusable workflow file under `docs/vibes/reusable-prompts/`.
-- Reusable prompts create and refresh the project docs.
-- Reusable prompts should follow the file responsibilities and stable headings defined in this contract.
-- Reusable prompts may be split into bootstrap, refresh, and parity families.
-
-### Runtime Modes
-
-Use two operating modes.
-
-| Mode | Typical request | Default path | Reusable prompts |
-| --- | --- | --- | --- |
-| Normal work | build, create, fix, test, review, or analyze a feature, bug, or code path | user prompt -> instructions -> relevant project docs -> optional skill -> output | No |
-| Template or doc maintenance | bootstrap docs, refresh docs after a material change, run parity, or update template structure | maintenance request -> reusable prompt or maintenance workflow -> contract or docs update | Yes, when bootstrap, refresh, or parity is the task |
-
-### Request Routing Examples
-
-| User request | Mode | Read first | Skill | Expected output |
-| --- | --- | --- | --- | --- |
-| "create evaluation feature api" | Normal work | `foundation/architecture.md`, `foundation/prd.md`, `foundation/status.md`, and any relevant API docs | Optional, usually `api-design` only if the boundary is non-trivial | Implemented API change or design-ready boundary update |
-| "test evaluation feature api" | Normal work | `technical/testing.md`, `foundation/architecture.md`, and relevant feature docs | Usually `test-authoring` | Verification strategy, recommended checks, and tests when needed |
-| "verify this feature against the docs, contract, and code" | Normal work | `technical/testing.md`, `foundation/architecture.md`, `foundation/prd.md`, `foundation/status.md`, and relevant technical-guidelines or feature docs | Usually `full-verification` | Routed verification path, selected specialist skill, and checks or findings |
-| "analyze why evaluation api is flaky" | Normal work | `foundation/architecture.md`, `technical/testing.md`, `foundation/status.md`, and runtime evidence | Usually `analysis` or `code-audit` | Findings, likely cause, and next action |
-| "what should we improve before this workflow is production-ready" | Normal work | `foundation/prd.md`, `foundation/status.md`, `foundation/architecture.md`, `technical/testing.md`, and relevant workflow docs | Usually `project-elevation` | Prioritized improvement roadmap grounded in current scope and maturity |
-| "refresh docs after architecture change" | Template or doc maintenance | `docs/eyehateagent-contract.md`, `foundation/architecture.md`, and the owning docs | Optional | Updated docs only, usually through the refresh reusable prompt workflow |
-| "audit reusable prompt and skill drift" | Template or doc maintenance | `docs/eyehateagent-contract.md`, platform instruction surfaces, reusable prompt files, skill files, and summary docs | Usually `parity` | Drift report and ownership-level fixes |
-
-### Skill Invocation Rule
-
-- Read the relevant project docs first.
-- Act directly when the task is local, obvious after reading the docs, and primarily implementation, editing, or straightforward verification.
-- Use a skill when the task benefits from a reusable expert-role method, deeper reasoning, boundary-specific design, expert auditing, or expert verification planning.
-- If the user explicitly requests a skill, treat that as a stronger signal than automatic judgment and use the skill unless it is clearly irrelevant or unnecessary for the task.
-- Treat attached skill context as a relevance hint, not an automatic requirement.
-- If a requested or attached skill is clearly unnecessary, say so briefly and proceed directly unless the user insists.
-- Use `full-verification` when the user asks for broad verification against project docs, contract, guidelines, code, or repository state and the dominant specialist check is not obvious up front.
-- Prefer the single most relevant skill instead of chaining multiple skills by default.
-- Skills support execution; they do not replace project docs as the source of truth.
-
-### Skill Selection Matrix
-
-Use this matrix when multiple skills sound plausible.
-
-| If the user mainly wants... | Usually choose | Choose this over... | Expected outcome |
-| --- | --- | --- | --- |
-| Broad verification against project docs, contract, code, guidelines, or repository state | `full-verification` | a specialist skill when the user wants one broad entry point and the best verification mode is not yet clear | Routed specialist skill, verification plan, and checks or findings |
-| Root-cause explanation, trade-off judgment, or architecture reasoning | `analysis` | `project-elevation` when the question is about current behavior or decision quality rather than future improvements | Findings, reasoning, recommendation, and confidence |
-| Correctness review of existing code, logic, or boundary safety | `code-audit` | `analysis` when the task is inspecting an implemented artifact for bugs, dead paths, or boundary violations | Severity-ranked findings and corrective direction |
-| Contract or boundary shape for an API, service, repository, adapter, or event | `api-design` | `analysis` when the primary deliverable is a contract or interface shape rather than a broad judgment memo | Proposed boundary design, validation rules, and verification strategy |
-| Verification boundary, check type, commands, and whether tests should be added | `test-authoring` | `code-audit` when the question is how to verify a change, not whether the implementation is correct | Verification strategy and tests when needed |
-| Forward-looking improvements, missing capabilities, or what to do next | `project-elevation` | `analysis` when the task is prioritizing realistic next improvements rather than explaining existing behavior | Prioritized improvement roadmap |
-| Drift, contradiction, or ownership mismatches across docs, platform instruction surfaces, skills, and prompts | `parity` | `analysis` when the problem is repository-wide disagreement rather than local technical reasoning | Classified drift findings with ownership-level fixes |
-
-### Decision Precedence
-
-Resolve routing and behavior decisions in this order:
-
-1. the user's requested goal and output
-2. the user's explicit constraints or preferences, including an explicit request to use a specific skill
-3. the active contract and the owning project docs
-4. attached context such as skill files, notes, or examples, treated as relevance hints unless the user made them mandatory
-5. automatic agent judgment
-
-If a higher-precedence signal conflicts with a lower one, follow the higher signal unless it is impossible, unsafe, or clearly irrelevant; explain the conflict briefly when that affects the outcome.
-
-### Failure And Fallback Rules
-
-- If a required project doc is missing, note the gap explicitly, create or update the smallest owning doc that unblocks the task, and limit confidence until the gap is resolved.
-- If project docs conflict, treat the contract and the owning doc as the source of truth, classify the mismatch as drift, and update the owner or ask the user when ownership is still unclear.
-- If code, tests, configs, or runtime-facing artifacts conflict with active docs and the repository does not explicitly define which side is authoritative for that fact, do not guess; surface the conflict, cite the evidence, and ask the user before choosing the fix path.
-- If the repository clearly establishes authority for that fact, state the governing evidence explicitly and proceed using the owning surface.
-- When mapping legacy or reference docs 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, not the source-of-truth ownership model.
-- If legacy or reference docs show that a still-valid optional doc, guideline set, or phased-planning surface should be active under `docs/project-docs/`, promote it into the active owner-doc set and update the relevant registries instead of leaving it only in reference folders.
-- If legacy or reference docs contain valuable project-specific information (such as 'Decision Rationale') that does not fit into standard template headings, do not discard it. Evaluate its value and decide whether it should become a new custom section in an existing document or if it warrants a new separate file. If ambiguous, ask the user before discarding the knowledge.
-- When no project docs or legacy docs exist and the codebase is the only source of truth, inspect code, comments, commit messages, configs, tests, and repository structure for valuable domain knowledge that goes beyond standard template headings. Surface these findings and decide whether each should become a new custom section in an existing document, a new separate file, or should be confirmed with the user first. Mark codebase-derived facts with lower confidence than doc-derived facts until the user confirms them.
-- If the user requests a skill that is clearly unnecessary or mismatched, say so briefly and proceed directly unless the user insists.
-- If attached context is outdated or conflicts with active docs, prefer the active docs and treat the attachment as reference only.
-- If no suitable skill exists, continue through the direct path using the contract, project docs, and the strongest applicable non-skill method.
-- If no stronger validation exists, follow the fallback rules in `testing.md` and state the limitation explicitly.
-
-### Output By Mode
-
-| Mode | Must end with |
-| --- | --- |
-| Normal work | The requested output, the narrowest applicable validation or an explicit limitation, and a documentation-sync update or check when ownership changed |
-| Template or doc maintenance | Updated docs, platform instruction surfaces, skills, or reusable prompts, a consistency validation step, and any unresolved drift or follow-up items |
-
-These are completion requirements, not a universal response template.
-
-When a repository defines a default live-response shape in its platform instruction surfaces, treat that shape as a lightweight baseline only.
-If multiple output-shape signals apply, use this precedence:
-
-1. the user's explicit format request
-2. the active mode or mode-specific agent file
-3. the active skill or reusable prompt `Output Contract`
-4. the platform instruction surface default live-response shape
-5. the agent's local judgment
-
----
-
-## Repository Taxonomy
-
-Use the repository in five categories.
-
-| Category | Primary paths | Role |
-| --- | --- | --- |
-| Platform instruction surfaces | `.github/instructions/`, `.claude/rules/`, `.agents/rules/` | Agent-platform specific entry points that enforce generic behavior (via embedded Contract Essentials) and point to project docs |
-| Docs anchors | `docs/eyehateagent-contract.md`, `docs/eyehateagent-maintenance.md` | Documentation-level routing, governance, and template-maintainer anchors |
-| Active project docs | `docs/project-docs/` | Canonical project-specific truth for scope, architecture, testing, workflow, and conventions |
-| Reusable template assets | `docs/vibes/` | Reusable prompts, skills, and starter assets that operate from the active contract |
-| Reference or archive material | explicit non-contract paths such as `archive/`, `reference/`, `docs-legacy/`, `docs-old/`, or other clearly named folders | Historical, migrated, or example material that may inform work but must not override active contract truth |
-
-`docs/eyehateagent-contract.md` plus the owning docs under `docs/project-docs/` form the active contract layer.
-Project-specific facts still belong in `docs/project-docs/`.
-When present, `docs/eyehateagent-maintenance.md` remains template-repo-only governance and must not become the owner of adopted-repository facts.
-When adopting Eye Hate Agent into a repo that already has another documentation format, move the old docs you want to preserve into a clearly non-owner reference folder such as `docs-legacy/`, `docs-old/`, or `archive/legacy-docs/` before refresh.
-Reusable prompts may read those folders as reference input during migration, but `docs/project-docs/` remains the only active owner-doc surface.
-
----
-
-## Supported Adoption Topologies
-
-This contract formally supports two adoption topologies.
-
-| Topology | Status | Contract rule |
-| --- | --- | --- |
-| Scenario 1 — distributed self-contained repos | Supported default | each adopted repo keeps its own contract, project docs, rule surfaces, and reusable template assets |
-| Scenario 2 — shared template repo with local project docs | Supported alternative | each adopted repo keeps its own contract and project docs, while one shared template repo may own reusable assets for multiple adopted repos |
-| Scenario 3 — centralized portfolio-doc repo | Not supported by this contract | possible only as a redesign, because it moves project-specific truth out of each adopted repo |
-
-Rules that stay true in both supported topologies:
-
-- each adopted repo keeps its own `docs/eyehateagent-contract.md`
-- each adopted repo keeps its own local `docs/project-docs/` as the owner of repo-specific truth
-- `docs/eyehateagent-maintenance.md` remains template-repo-only governance
-- reusable prompts, reusable skills, and starter assets may be local in each repo or centralized in one shared template repo
-- platform instruction surfaces may be centralized only when the agent platform can reliably consume them there; otherwise keep local mirrors that point back to the same contract
-
-Scenario 3 is intentionally outside this contract because it changes the ownership model rather than only changing asset placement.
-
----
-
-## Spec-Driven Development (SDD) Workflow
-
-Eye Hate Agent enforces a strict Spec-Driven Development (SDD) lifecycle. 
-**"Specification Dictates Implementation."**
-
-### Workflow Sequence
-
-1. **Update Specs First**: All new requirements, architectural changes, or bug fixes must first be documented in the relevant project docs (e.g., `prd.md` or `architecture.md`).
-2. **Generate Tests (TDD)**: Test cases must be authored based *only* on the updated specifications.
-3. **Generate Code**: Implementation code is written to pass the tests and fulfill the exact acceptance criteria defined in the specs. AI agents must refuse to write code for features not explicitly listed in the spec.
-4. **Map to Specs**: Every code change must logically map back to a specific requirement, acceptance criterion, or architectural rule defined in the project docs.
-
----
-
-## Required Document Set
-
-| File Path | Priority | Purpose |
-| --- | --- | --- |
-| `docs/eyehateagent-contract.md` | Mandatory | Docs anchor for routing, ownership, and precedence |
-| `index.md` | Mandatory | Links to all active documents |
-| `getting-started.md` | Mandatory | Runbook for developers (setup, onboarding) |
-| `foundation/prd.md` | Mandatory | Vision, personas, requirements, flows, and acceptance criteria |
-| `foundation/architecture.md` | Mandatory | Stack, runtime model, boundaries, patterns |
-| `foundation/workflow.md` | Mandatory | Local dev loop, PR process, team rules |
-| `foundation/status.md` | Mandatory | Roadmap, current implementation state |
-| `foundation/phases.md` | Mandatory | Phases of project, agile sprint tracking, and backlogs |
-| `foundation/changelog.md` | Optional | Record of changes per release |
-| `foundation/feature-inventory.md` | Optional | Detailed feature catalog linked to codebase |
-| `operations/ci-cd.md` | Mandatory | Automate build/test/deploy pipeline |
-| `operations/production-runbook.md` | Mandatory | Deployment steps and ops procedures |
-| `operations/governance.md` | Optional | Release conventions, branch strategy |
-| `operations/compliance.md` | Optional | Data privacy rules (GDPR) |
-| `operations/observability.md` | Optional | Logging, tracing, metrics |
-| `operations/security.md` | Optional | Identify threats & mitigations |
-| `technical/testing.md` | Mandatory | Verification matrix, test types, and testing procedures |
-| `technical/api-contract.md` | Mandatory | Service endpoints and messages |
-| `technical/database.md` | Mandatory | Data structures, database schema, and Data Dictionary |
-| `technical/ui-ux.md` | Mandatory | Design documents |
-| `technical/error-handling.md` | Optional | Standardized error codes and shapes |
-| `technical/internationalization.md` | Optional | Supported languages, i18n workflows |
-
-**Flexible Baselines Principle**: The EHA templates are a baseline. Both humans and AI agents are empowered to modify, remove, or combine these template headings and files if a specific repository requires a leaner approach, provided the core SDD rule ("Specification Dictates Implementation") is preserved.
-
-### Registry Policy
-
-- Keep the always-required core docs explicit in this contract. Do not use a registry to replace `foundation/prd.md`, `foundation/architecture.md`, `technical/testing.md`, `foundation/workflow.md`, or `foundation/status.md`.
-- Use `docs/project-docs/index.md` as the authoritative registry for optional and conditional regular project docs in a repo.
-- Use `docs/project-docs/technical-guidelines/index.md` as the authoritative registry for active guideline types in a repo.
-- A registry entry activates a known optional doc type or guideline type for bootstrap, refresh, and parity behavior even if no starter template file exists.
-- Starter template files under `docs/vibes/project-docs-template/` are recommended references, not the activation mechanism.
-- Registry entries for regular docs should capture at least file path, purpose, status, owner, and creation trigger.
-- Registry entries for guideline docs should capture at least file path, domain, purpose, owner, and review trigger.
-- If a brand-new regular doc type should be scaffolded without a starter template file, define its stable headings or equivalent structure in this contract first.
-
-If you want to add your own known optional regular doc type to the template system, add a row to `docs/vibes/project-docs-template/index.md` first.
-If you want to add your own known guideline type to the template system, add a row to `docs/vibes/project-docs-template/technical-guidelines/index.md` first.
-If the new doc class needs a new stable heading pattern or new ownership rule, update this contract before relying on bootstrap to scaffold it.
-
-### Guideline Policy
-
-- Keep guidelines focused on technical guidance, not on broad project summary; if a fact is general repository truth, it belongs in the core project docs.
-- A target repo is fully documented when the core project docs describe the repository generally and the active guidelines describe the durable technical rules that recurring work should follow.
-- Create a guideline only when a domain has durable cross-cutting rules that would otherwise be repeated across tasks, reviews, or features.
-- When any guideline files exist, create and maintain `technical-guidelines/index.md` as the authoritative registry for the active guideline set.
-- Keep one primary domain per guideline file so ownership stays clear.
-- Avoid placeholder guideline files; omit a domain until the repository has real guidance worth preserving.
-- Avoid copying the same rules into `foundation/architecture.md`, `technical/testing.md`, or `foundation/prd.md`; instead, cross-reference the owning guideline.
-- For a fully documented target repo, the baseline recommended starter set is: API, database, logging, error handling, JSON, code style, and design patterns.
-- Add other guideline domains only when the project needs them, such as UI, security, observability, performance, AI, configuration, or migrations.
-
----
-
-## Stable Headings Agents Can Depend On
-
-These headings should remain stable across projects whenever the file exists. The list of stable headings is a minimum baseline. All active project docs now use a universal core heading block before domain-specific headings.
-
-### Universal Core Headings (All Files)
-
-- `## 1. Description`
-- `## 2. Important`
-- `## 3. Table of Contents`
-- `## 4. Scope`
-- `## 5. Goals`
-- `## 6. Non Goals`
-
-### `foundation/prd.md`
-
-- `## 7. Vision Statement`
-- `## 8. Target Personas`
-- `## 9. Core Business Value`
-- `## 10. User Journeys & App Flow`
-- `## 11. Feature Workflows`
-- `## 12. Functional Requirements`
-- `## 13. Non-Functional Requirements`
-- `## 14. Acceptance Criteria`
-- `## 15. External Dependencies & Partners`
-- `## 16. Success Metrics`
-
-### `foundation/architecture.md`
-
-- `## 7. Tech Stack Overview`
-- `## 8. Architecture Pattern`
-- `## 9. System Flow`
-- `## 10. Data Flow`
-- `## 11. Tools Integration`
-- `## 12. Global Parameters and Constraints`
-- `## 13. Architecture Decision Records (ADRs)`
-
-### `technical/testing.md`
-
-- `## 7. Verification Policy & Objectives`
-- `## 8. Verification Matrix & Coverage`
-- `## 9. Test Layers & Environments`
-- `## 10. Commands & CI Gates`
-- `## 11. Naming & File Conventions`
-- `## 12. Manual Checks & Fallbacks`
-
-### `technical/database.md`
-
-- `## 7. Database Architecture`
-- `## 8. Entity Relationship Diagram (ERD)`
-- `## 9. Schema Definitions (Tables/Collections)`
-- `## 10. Indexes & Performance`
-- `## 11. Migration Strategy`
-- `## 12. Data Dictionary`
-
-### `foundation/status.md`
-
-- `## 7. Current State`
-- `## 8. Execution Map`
-- `## 9. Workstreams`
-
-### `foundation/phases.md`
-
-- `## 7. Phases Definition`
-- `## 8. Sprint Tracker`
-- `## 9. Active Tasks` (This acts as the unified Backlog)
-
-### `docs/eyehateagent-maintenance.md` (if present)
-
-- `## 1. Summary`
-- `## 2. Scope`
-- `## 3. Ownership Boundaries`
-- `## 4. Change Classes`
-- `## 5. Compatibility And Breaking Changes`
-- `## 6. Deprecation Policy`
-- `## 7. Maintainer Workflow`
-
-### `technical-guidelines/index.md` (if present)
-
-- `## 7. When To Add A Guideline`
-- `## 8. Active Guidelines`
-- `## 9. Stable Headings`
-- `## 10. Ownership And Review`
-
-If a project uses different headings, keep a clear cross-reference at the top of the file so agents can still find the equivalent sections quickly.
-
----
-
-## Naming And Surface Rules
-
-- Keep the anchor filenames stable inside `docs/`: `eyehateagent-contract.md` and `eyehateagent-maintenance.md`.
-- Keep the canonical project-doc paths stable inside `docs/project-docs/`: `foundation/prd.md`, `foundation/architecture.md`, `foundation/workflow.md`, `foundation/status.md`, `foundation/phases.md`, `technical/testing.md`.
-- Name reusable assets by job and scope, not by one adopted project's product name or stack.
-- Keep mirrored instruction files aligned by base name and meaning, even when platform-specific extensions or frontmatter fields differ.
-- Use numeric prefixes only when a surface is intentionally ordered as a small canonical sequence.
-- Prefer semantic names such as `project-docs-refresh` or `code-audit` over vague labels that hide the asset's purpose.
-- If a path is reference-only, label it clearly so it cannot be mistaken for active workflow or contract state.
-
----
-
-## Machine-Readable Conventions
-
-- Keep filenames stable.
-- Use explicit headings instead of burying key rules in prose.
-- Prefer summary tables for commands, stack, or decision matrices.
-- Put the **durable truth** in project docs, not in reusable prompt text or skill text.
-- Treat `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` as the authoritative inventories for optional regular docs and guideline types when they exist.
-- When a fact changes, update the owning project doc first, then update any dependent platform instruction surfaces, skills, or reusable prompts that quote or summarize it.
-- Mirror platform instruction metadata where the platform supports the same field set.
-
----
-
-## Ownership Rules
-
-| Type of information | Owning location |
-| --- | --- |
-| Contract routing, precedence, stable structures, and adoption rules | `docs/eyehateagent-contract.md` |
-| Vision, personas, requirements, flows, and acceptance criteria | `foundation/prd.md` |
-| Stack and architecture decisions | `foundation/architecture.md` |
-| Local dev loop, PR process, team rules | `foundation/workflow.md` |
-| Production environment operation, release, rollback, and smoke checks | `operations/production-runbook.md` if present |
-| Verification commands, environments, and quality gates | `technical/testing.md` |
-| Execution plan and progress | `foundation/status.md` |
-| Agile sprint tracking and backlogs | `foundation/phases.md` |
-| Optional and conditional regular project-doc inventory | `index.md` when present |
-| Template governance, lifecycle, and deprecation | `docs/eyehateagent-maintenance.md` if present |
-| Guideline inventory, guideline scope, and review ownership | `technical-guidelines/index.md` when present |
-| Domain-specific technical rules, implementation conventions, and preferred patterns | `technical-guidelines/*` |
-| Reusable prompt behavior | `docs/vibes/reusable-prompts/` in the adopted repo or in the shared template repo chosen by the topology |
-| Skill procedure behavior | `docs/vibes/skills/` in the adopted repo or in the shared template repo chosen by the topology |
-
-Do not duplicate the same rule across multiple files unless one file is explicitly a summary or index of the owning document.
-In Scenario 2, only reusable assets may centralize. Project-specific facts must remain local to the adopted repo.
-
----
-
-## How Agents Should Use This Contract
-
-### When writing or updating rules
-
-- Keep the rule generic.
-- Point the rule at the relevant project docs in `docs/project-docs/`.
-- Preserve the normal-work versus template-maintenance distinction defined in the operating model.
-- If a rule defines a default live-response shape, keep it short and treat it as a baseline rather than a universal override.
-- Avoid embedding concrete stack-specific commands directly unless the repository has intentionally chosen to keep them in the rule.
-
-### When writing or updating skills
-
-- State the **required project-doc inputs** near the top of the skill.
-- Use a stable top-level section model: `Required Project Inputs`, `When To Use`, `Procedure`, `Output Contract`, `Quality Checks`, `Anti-Patterns`, and `Example Requests`.
-- Keep skill-specific tables, matrices, and checklists inside those sections instead of inventing new top-level structure for each skill.
-- Describe a reusable expert-role procedure that adapts after reading those docs.
-- Make the boundary against neighboring skills explicit when routing confusion is likely.
-- Avoid binding the skill to one stack, one framework, or one package set unless the skill itself is intentionally stack-specific.
-
-### When writing or updating reusable prompts
-
-- Use this contract to decide which docs to generate or refresh.
-- Treat `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` as the inventory source of truth for optional regular docs and guideline types when they exist.
-- When clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/` exist, treat them as secondary migration input only and not as owner docs.
-- When mapping legacy artifacts to active docs, use the document's governed concern and content as the primary signal. Do not assume a legacy name must be preserved just because it does not match template terminology.
-- When those reference folders contain still-valid optional-doc, guideline, or phased-planning material, promote the justified docs into the active owner-doc set and update the relevant registries instead of leaving the material reference-only.
-- Evaluate valuable information from legacy docs or codebase analysis that lacks a standard template heading. Do not discard it; instead, decide whether it should become a new custom section in an existing document or a new separate file, and ask the user if the best approach is ambiguous.
-- Use a stable top-level section model: `Goal`, `Required Behavior`, `Output Contract`, `Final Pass`, and `Inputs`.
-- Use optional top-level sections only when needed, such as `Scope`, `Minimum Outputs`, `Constraints`, or `Ownership Examples`.
-- Keep review sequences, category examples, and file-by-file expectations inside those sections instead of inventing unrelated top-level structure.
-- Keep output structure stable.
-- Update only the affected docs on refresh reusable prompts.
-- Add a consistency pass when changing architecture, testing, or workflow-related docs.
-
----
-
-## Extension Rules That Must Survive Adoption
-
-These rules belong in the contract because downstream repositories may remove `docs/eyehateagent-maintenance.md`.
-
-| If you are adding or changing... | Update first | Usually also update | Core rule |
-| --- | --- | --- | --- |
-| a reusable skill | the owning skill file in `docs/vibes/skills/` for the chosen topology | `docs/eyehateagent-contract.md` if the expected skill structure or inputs changed | keep the skill procedural, expert-role, and start from project docs |
-| a rule or instruction point | the platform instruction surfaces in the owning template | `docs/eyehateagent-contract.md` if routing, precedence, fallback, output-by-mode, or ownership changed; `testing.md` if verification expectations changed; local instruction surfaces if a platform requires repo-local instruction loading | keep the rule generic and point back to project docs |
-| a project-doc owner or reusable optional doc | the owning doc first; if it becomes template-wide, update `docs/eyehateagent-contract.md` first | `docs/vibes/project-docs-template/` if adopters should get a starter version; onboarding or adoption docs if discovery changes | if only one adopted repository needs it, keep it local to that repository instead of promoting it into the template |
-| the contract itself | `docs/eyehateagent-contract.md` | platform instruction surfaces (mirrored rule files), affected skills, reusable prompts, onboarding docs, summaries, and `changelog.md` | contract changes are highest-impact and should be treated as template-level changes |
-
-Notes:
-
-- Downstream repositories should still be able to follow these rules after `docs/eyehateagent-maintenance.md` is removed.
-- Template-repo-only workflow remains in `docs/eyehateagent-maintenance.md`.
-- In Scenario 2, the shared template repo is the owner of reusable assets, but not of adopted-repository project facts.
-- Registry entries activate known optional doc types and guideline types in a repo; contract updates are needed only when introducing a new doc class, a new stable heading pattern, or a new ownership model.
-
----
-
-## Adoption Checklists For Supported Topologies
-
-### Scenario 1 — Distributed Self-Contained Repos
-
-1. Copy the template into the adopted repository.
-2. Keep `docs/eyehateagent-contract.md`.
-3. Populate `foundation/prd.md`, `foundation/architecture.md`, `foundation/workflow.md`, `foundation/status.md`, and `technical/testing.md` under `docs/project-docs/` first.
-4. If optional or conditional regular docs are active, declare them in `docs/project-docs/index.md`.
-5. If guideline docs are active, declare them in `docs/project-docs/technical-guidelines/index.md`.
-6. Remove `docs/eyehateagent-maintenance.md` from the adopted repository.
-7. Review platform instruction surfaces and skills only for template-level changes, not project-specific facts.
-8. Use reusable prompts to create or refresh docs instead of editing many scattered files by hand.
-
-### Scenario 2 — Shared Template Repo With Local Project Docs
-
-1. Keep the shared template repo available in the same workspace or other agent-visible context.
-2. Copy `docs/eyehateagent-contract.md` into each adopted repository.
-3. Populate `foundation/prd.md`, `foundation/architecture.md`, `foundation/workflow.md`, `foundation/status.md`, and `technical/testing.md` under each adopted repo's local `docs/project-docs/` path.
-4. If optional or conditional regular docs are active, declare them in each adopted repo's local `docs/project-docs/index.md`.
-5. If guideline docs are active, declare them in each adopted repo's local `docs/project-docs/technical-guidelines/index.md`.
-6. Keep reusable prompts, reusable skills, and starter assets in the shared template repo unless a local copy is intentionally needed.
-7. Keep local instruction mirrors only when an agent platform requires repo-local instruction loading.
-8. Remove `docs/eyehateagent-maintenance.md` from adopted repositories.
-9. Do not move adopted-repository project facts into the shared template repo.
-10. Run reusable prompts against the adopted repo's local owner docs, not against centralized portfolio summaries.
-
----
-
-## Change Policy
-
-If this contract changes:
-
-1. Update this file first.
-2. Update the platform instruction surfaces that reference it.
-3. If one platform instruction surface changes, update the other surfaces in the same change unless divergence is intentional and documented.
-4. Update any skill or reusable prompt that depends on the old contract.
-5. Run a consistency review so the template does not drift.