@sallmarta/eye-hate-agent 1.0.3 → 1.0.4

package/README.md

@@ -1,67 +1,91 @@
 # Eye Hate Agent (EHA)
 
-A CLI engine that generates a shared set of rules, skills, and documentation workflows for AI agents (Claude, GitHub Copilot) directly into your repository.
+A simple **Spec-Driven Development (SDD)**. Unified set of rules, specialist skills, and dynamic project documentation workflows, standardizing how AI coding agents receive instructions to make collaborative development completely predictable and highly efficient.
 
 ---
 
-## Quick Start
+## Get Started
 
 ### 1. Initialize EHA in your project
-Run the wizard in your project root to generate the required agent instructions:
-
+Run directly in **your project root**:
+```bash
+$ npx @sallmarta/eye-hate-agent
+```
+*Or install **globally** and run it:*
 ```bash
-npx @sallmarta/eye-hate-agent
+$ npm i -g @sallmarta/eye-hate-agent
+$ eha
 ```
-*(Or install globally: `npm i -g @sallmarta/eye-hate-agent` and run `eha`)*
 
 ### 2. Trigger your agent
-Once generated, the files are immediately ready to use in your IDE. Trigger the workflows using your agent's native slash commands, file mentions, or prompt attachments (e.g., typing `/eha-bootstrap` or attaching the bootstrap file in chat).
+Once projected, EHA files are immediately active in your IDE. Trigger the workflows using your agent's native slash commands, file mentions, or prompt attachments (read more on [EHA Commands](#eha-commands)).
 
-### 3. Commit the generated files
-The generated files (`.claude/` or `.github/`) act as your project's AI contract. Commit them to version control so your whole team shares the same agent behaviors and documentation standards.
+### 3. Commit the contract
+The projected files (`.claude/`, `.github/`, or `.agents/`) act as your project's AI contract.
 
 ---
 
-## CLI Commands
+## EHA Commands
 
-```bash
-eha [init]          # Wizard: detect project root, choose agent, generate files
-eha init [agent]    # Set up EHA directly (e.g., claude, copilot, etc.)
-eha doctor          # Verify generated files and EHA status
-eha remove          # Remove all EHA-generated files and config
-```
+Once initialized, EHA projects a series of interactive workflows directly into your agent's configuration directory (e.g., `.agents/` or `.github/`). You can trigger these workflows inside your IDE chat using slash commands, file mentions, or prompt attachments:
+
+| Slash Trigger | Primary Purpose |
+| :--- | :--- |
+| **`/eha-bootstrap`** | Initializes the repository's SDD document set, generating a tailored 4-layer taxonomy (Lite, Standard, Enterprise). |
+| **`/eha-refresh`** | Re-aligns and updates the existing documentation set when project scope, stack, or directory layouts shift. |
+| **`/eha-parity`** | Audits the repository to check for document drift, stale headings, structural errors, and ownership mismatches. |
+| **`/sdd-discuss`** | Initiates collaborative scoping and brainstorming sessions to align intent and draft specs before writing code. |
+| **`/sdd-execute`** | Spec-Driven Development execution—translates agreed specifications into robust, verified, and tested code. |
 
 ---
 
-## What Gets Generated
+## EHA CLI Command
 
-Running `eha` detects your chosen agent and outputs fully self-contained files into its native configuration directory (e.g., `.claude/`, `.github/`, or `.antigravity/`). Every file is pre-injected with EHA's compact rules (4-layer taxonomy, ownership map, and Spec-Driven Development rules).
+The EHA CLI provides a lightweight, frictionless setup and maintenance toolbelt:
 
-Regardless of the target agent, the output always includes:
-- **Workflows**: Ready-to-use commands for project bootstrapping, doc refreshing, parity checks, and discussions.
-- **Skills**: Expert capabilities like `code-audit`, `api-design`, `test-authoring`, and `full-verification`.
-- **Rules**: A central instruction file enforcing the EHA project contract.
+| 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 remove` | Safely deletes EHA's configuration directories, manifest registries, and generated contract files from your repository. |
 
 ---
 
 ## Updating
 
-When a new version of EHA is released, simply run `eha` in your repository again. The engine will detect the version mismatch and automatically prompt you to regenerate the files with the latest improvements.
+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.
 
 ---
 
-## Uninstallation & Cleanup
+## Uninstallation
 
 To completely remove EHA from your project and device:
 
 ### 1. Remove project files
-Run the following command in your project root to clean up all generated AI context files and project metadata (`.eha/`):
+Run the following command in your project root to clean up all projected AI files:
 ```bash
-eha remove
+$ eha remove
 ```
 
-### 2. Uninstall the CLI (Total Removal)
+### 2. Uninstall the CLI globally
 To completely remove the CLI from your device, run:
 ```bash
-npm uninstall -g @sallmarta/eye-hate-agent
+$ npm uninstall -g @sallmarta/eye-hate-agent
 ```
+
+---
+
+## EHA Philosophy
+
+Eye Hate Agent is built upon a core set of operational beliefs designed to optimize the synergy between human developers and AI coding agents:
+
+1. **Readability First (Dual-Audience Design)**: Every registry, template, and workspace document generated by EHA strictly adheres to standard markdown structures, numbered stable headings, and clean tables. This ensures maximum readability for humans while granting AI agents 100% syntactic parsing clarity (completely eliminating context loss).
+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.

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

@@ -1,66 +1,208 @@
-# Index
+# Project Docs Registry
 
-Last update: YYYY-MM-DD
+Last update: 2026-06-01
 
-Status: [Proposed | Draft | Live | Deprecated | Archived]
+Status: Live
 
 ---
 
 ## 1. Description
-Use this index to list the optional and conditional regular project docs that are active for a repository. The always-required core docs are defined by the contract and do not need registry entries to exist. This index is the authoritative registry for optional and conditional regular docs; starter template files are recommended references, not the activation mechanism.
+This index is the master registry and layout definition for all Spec-Driven Development (SDD) documentation within EHA-adopting repositories. It defines the universal stable headings schema and active document types.
 
 ## 2. Important
-Notes of important findings or critical constraints. Can be empty.
+All documentation generated under `docs/project-docs/` (except `index.md`, `getting-started.md`, and guideline registries) must strictly implement the Universal Stable Headings schema and incorporate the unique domain-specific headings defined below.
 
 ## 3. Table of Contents
-[Generate a hyperlinked table of contents here containing ALL headings in this file (1 through N). Use standard markdown links, e.g., - [1. Description](#1-description)]
+- [1. Description](#1-description)
+- [2. Important](#2-important)
+- [3. Table of Contents](#3-table-of-contents)
+- [4. Scope](#4-scope)
+- [5. Goals](#5-goals)
+- [6. Non Goals](#6-non-goals)
+- [7. Universal Stable Headings](#7-universal-stable-headings)
+- [8. Active Doc Type Registry](#8-active-doc-type-registry)
+- [9. Domain-Specific Headings Catalog](#9-domain-specific-headings-catalog)
 
 ## 4. Scope
-The boundaries of what this document covers.
+Covers the structural headings, layers (`foundation/`, `development/`, `operations/`), and domain headings for EHA-governed repositories.
 
 ## 5. Goals
-What we aim to achieve with this specific document.
+Eliminate template boilerplate redundancy, prevent cross-document drift, and lower agent context consumption.
 
 ## 6. Non Goals
-What is explicitly excluded from the scope of this document.
-
-## 7. How to Use This Documentation
-A guide for new developers on where to start reading.
-
-## 8. Documentation Ownership
-Who is responsible for keeping specific files up to date (e.g., "Backend team owns `api-contract.md`").
-
-## 9. Foundational Required Docs
-- `prd.md`
-- `architecture.md`
-- `testing.md`
-- `workflow.md`
-- `status.md`
-
-## 10. Optional And Conditional Docs
-| File | Purpose | Status | Owner | Creation trigger |
-| --- | --- | --- | --- | --- |
-| `changelog.md` | Release or milestone change history | conditional | TBD | When changes need release or milestone tracking |
-| `getting-started.md` | Setup, onboarding, and first-run guidance | conditional | TBD | When setup or onboarding needs a dedicated owner doc |
-| `feature-inventory.md` | Detailed feature catalog | conditional | TBD | When the feature surface is large enough to need inventory-level tracking |
-| `production-runbook.md` | Release, rollback, smoke-check, and recovery guidance | conditional | TBD | Before production operation needs a dedicated runbook |
-| `phases/index.md` | Multi-phase planning or epic registry | conditional | TBD | When roadmap work needs explicit phase tracking |
-| `YOUR_NEW_DOC.md` | State the purpose of the next optional regular doc here | conditional | TBD | State the creation trigger for the next optional regular doc here |
-
-Use status values such as `active`, `conditional`, `deprecated`, or `archived`. Add a new row in the `## 10. Optional And Conditional Docs` table above for each additional optional regular doc type that the repo activates.
-
-## 11. Registry Rules
-- Add a new row in the `## 10. Optional And Conditional Docs` table above when an optional or conditional regular doc becomes part of the repo's active documentation set.
-- A row in this index activates a known optional doc type for bootstrap, refresh, and parity behavior.
-- If no starter template file exists for a listed doc type, use the stable headings or ownership rules defined in the contract.
-- Keep this index aligned with the files that actually exist under `docs/project-docs/`.
-- If a listed doc is deprecated or archived, update its status rather than silently removing its history.
-
-## 12. Success Metrics
-How we measure if the goals of this document are achieved.
-
-## 13. Related Documents
-[Link to related document](path) - Short brief note about why it's related.
-
-## 14. Open Questions
-Any unresolved questions or assumptions. Can be empty.
+Does not define technical guidelines rules (refer to `technical-guidelines/index.md`).
+
+## 7. Universal Stable Headings
+Every project document must include these numbered headings in this exact order. Domain-specific headings go after § 6 and before the closing set. Feel free to add extra domain-specific headings if needed to capture important project context.
+
+### Opening Set:
+1. Description
+2. Important
+3. Table of Contents
+4. Scope
+5. Goals
+6. Non Goals
+
+### Closing Set (always last, in this order):
+- Success Metrics
+- Related Documents
+- Open Questions
+
+## 8. Active Doc Type Registry
+
+| Doc Type | Layer | Tier | Description |
+| :--- | :--- | :--- | :--- |
+| `getting-started.md` | Root | 1 | Orientation and local setup instructions. |
+| `foundation/prd.md` | foundation | 1 | Vision statement, target personas, user journeys, features. |
+| `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. |
+| `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. |
+| `development/ui-ux.md` | development | 2 | Design rules, wireframes, screen layouts, design tokens, responsive, a11y. |
+| `development/internationalization.md` | development | 3 | Languages support, translations flow, currency, dates. |
+| `operations/ci-cd.md` | operations | 2 | CI/CD pipelines, test gates, secrets handling, deploys. |
+| `operations/production-runbook.md` | operations | 3 | Release procedures, rollback, environment config, smoke checks. |
+| `operations/governance.md` | operations | 3 | Versioning policy, release cadence, code ownership rules. |
+| `operations/security-compliance.md` | operations | 3 | Threat mitigation, RBAC, encryption, data privacy/retention, audit logging. (Merged security + compliance) |
+| `operations/observability-error-handling.md` | operations | 3 | Log levels, error payloads, server fallbacks, alerts, dashboard metrics. (Merged observability + error handling) |
+| `[custom-path].md` | [layer] | [tier] | [Add custom document templates here as needed to activate additional files] |
+
+## 9. Domain-Specific Headings Catalog
+
+This catalog defines the baseline required domain-specific headings for each document type. When documenting a repository, both developers and AI agents are **NOT** limited to this baseline catalog; they must actively append additional, custom domain-specific headings to capture the unique features, patterns, and architectural realities discovered in the codebase.
+
+### `getting-started.md`
+- Prerequisites
+- First Steps
+- Local Setup
+- Verification
+- Troubleshooting
+
+### `foundation/prd.md`
+- Vision Statement
+- Target Personas
+- Core Business Value
+- User Journeys & App Flow
+- Feature Workflows
+- Functional Requirements
+- Non-Functional Requirements
+- Acceptance Criteria
+- External Dependencies & Partners
+
+### `foundation/architecture.md`
+- Tech Stack Overview
+- Architecture Pattern
+- System Flow
+- Data Flow
+- Tools Integration
+- Global Parameters and Constraints
+- Architecture Decision Records
+
+### `foundation/status.md`
+- Current State
+- Recent Accomplishments
+- Upcoming Focus
+- Key Metrics
+- Roadmap
+- Epics
+- Risks/Blockers
+
+### `foundation/workflow.md`
+- Local Dev Loop
+- Branching Strategy
+- PR & Code Review
+- Issue Tracking
+
+### `foundation/phases.md`
+- Overall Timeline
+- Feature Summary & Core Functions
+- Sub-Functions
+- Deprecated Features
+- Phase Registry
+- Sprint Tracker
+
+### `foundation/changelog.md`
+- [Unreleased] (Added/Changed/Deprecated/Removed/Fixed/Security entries)
+
+### `development/testing.md`
+- Verification Policy & Objectives
+- Verification Matrix & Coverage
+- Test Layers & Environments
+- Commands & CI Gates
+- Naming & File Conventions
+- Manual Checks & Fallbacks
+
+### `development/api-contract.md`
+- Base URL & Auth
+- Request/Response Format
+- Endpoints
+- Webhooks
+- Rate Limiting
+
+### `development/database.md`
+- DB Architecture
+- Schema Definitions
+- Indexes
+- Migration Strategy
+- Data Dictionary
+
+### `development/ui-ux.md`
+- Design Philosophy
+- Design System
+- Wireframing
+- Screen Layouts
+- Component Library
+- Responsive
+- Accessibility (A11y)
+- Design Handoff
+
+### `development/internationalization.md`
+- Supported Languages
+- Translation Workflow
+- Fallback Locales
+- Date & Currency
+
+### `operations/ci-cd.md`
+- Pipeline Architecture
+- Build Steps
+- Testing & Quality Gates
+- Deployment Environments
+- Secrets
+
+### `operations/production-runbook.md`
+- Environment Overview
+- Prerequisites & Access
+- Release Procedure
+- Smoke Checks
+- Rollback
+- Operational Notes
+
+### `operations/governance.md`
+- Versioning Policy
+- Release Cadence
+- Code Ownership
+- Contribution Guidelines
+
+### `operations/security-compliance.md`
+- Security Objectives & Threats
+- Access Control & RBAC
+- Data Encryption & Privacy
+- Data Retention
+- Audit Logging
+- Compliance Audits & Legal Disclaimers
+
+### `operations/observability-error-handling.md`
+- Logging Strategy
+- Standard Error Payloads
+- Global Error Codes
+- Client-Side Rules & Server Fallbacks
+- Metrics & Dashboards
+- Alerting Rules
+- Distributed Tracing
+
+### `[custom-path].md`
+- [Add the custom document's unique domain headings here, e.g., "Caching Strategy" or "Performance Budgets"]

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

@@ -1,24 +1,44 @@
-# Guidelines Index
+# Guidelines Registry
 
-Last update: YYYY-MM-DD
+Last update: 2026-06-01
 
-Status: [Proposed | Draft | Live | Deprecated | Archived]
+Status: Live
 
 ---
 
-## 1. Summary
-Use this index to list the active technical guideline documents for the repository. Core project docs explain the repository generally. Guidelines explain the durable technical rules that recurring implementation and review work should follow. This index is the authoritative registry for active guideline types; starter template files are recommended references, not the activation mechanism.
+## 1. Description
+This registry is the authoritative catalog and schema definition for all active technical guideline documents inside the repository. While core project documents explain the repository generally, technical guidelines document the durable, cross-cutting coding and design conventions that developers and AI agents must follow during implementation.
 
-## 2. When To Add A Guideline
-- Add a guideline when a technical domain has cross-cutting rules that would otherwise be repeated across tasks.
-- Do not create a guideline as a placeholder.
-- Keep one primary domain per guideline file.
-- If a rule is broad project truth, keep it in the core project docs and reference that doc here instead.
-- Add a new row in the `## 3. Active Guidelines` table below when activating a known guideline type, even if no starter template file exists for it yet.
+## 2. Important
+Guidelines are durable, codebase-level rulebooks. They must never be created as simple placeholders. A guideline is officially activated in bootstrap, refresh, and parity loops only when it has an active row registered in the Active Guidelines table below.
 
-## 3. Active Guidelines
-| Guideline | Domain | Purpose | Owner | Review trigger |
-| --- | --- | --- | --- | --- |
+## 3. Table of Contents
+- [1. Description](#1-description)
+- [2. Important](#2-important)
+- [3. Table of Contents](#3-table-of-contents)
+- [4. Scope](#4-scope)
+- [5. Goals](#5-goals)
+- [6. Non Goals](#6-non-goals)
+- [7. Active Guidelines Registry](#7-active-guidelines-registry)
+- [8. Registry Rules & Ownership](#8-registry-rules--ownership)
+- [9. Guideline Stable Headings](#9-guideline-stable-headings)
+- [10. Success Metrics](#10-success-metrics)
+- [11. Related Documents](#11-related-documents)
+- [12. Open Questions](#12-open-questions)
+
+## 4. Scope
+Covers the active guideline categories, ownership tracking, review triggers, and standard heading rules for technical guidelines.
+
+## 5. Goals
+Standardize the coding and architectural rules across the codebase, preventing design-pattern divergence and ensuring high code quality.
+
+## 6. Non Goals
+Does not document general project setup, business logic, or operational procedures (refer to the master project docs registry `index.md`).
+
+## 7. Active Guidelines Registry
+
+| Guideline | Domain | Purpose | Owner | Review Trigger |
+| :--- | :--- | :--- | :--- | :--- |
 | `technical-guidelines/api.md` | API | Request or response contracts, versioning rules, and integration boundaries | TBD | API contract or integration changes |
 | `technical-guidelines/database.md` | Database | Schema, migration, naming, and persistence rules | TBD | Schema or storage changes |
 | `technical-guidelines/logging.md` | Logging | Event naming, log levels, redaction, and correlation rules | TBD | Logging policy or observability changes |
@@ -29,24 +49,33 @@ Use this index to list the active technical guideline documents for the reposito
 | `technical-guidelines/internationalization.md` | i18n/l10n | Rules for i18n keys, fallbacks, and adding new languages | TBD | i18n tooling or language changes |
 | `technical-guidelines/testing.md` | Testing | Rules for writing tests, naming conventions, mocking, and coverage | TBD | Testing framework or coverage changes |
 | `technical-guidelines/ui-ux.md` | UI/UX | Rules for UI components, accessibility standards, and design system usage | TBD | Design system or component library changes |
-| `technical-guidelines/your-new-guideline.md` | State the domain of the next guideline here | State the purpose of the next guideline here | TBD | State the review trigger for the next guideline here |
+| `technical-guidelines/[custom-guideline].md` | [Domain] | [Durable technical rules and conventions for custom domain] | TBD | [Review trigger, e.g. "API or schema changes"] |
 
-Remove rows for inactive domains and add a new row in the `## 3. Active Guidelines` table above for any other active guideline files.
+Remove rows for inactive domains and add a new row in the `## 7. Active Guidelines Registry` table above for any other active guideline files.
 
-## 4. Ownership And Review
+## 8. Registry Rules & Ownership
 - Keep this index aligned with the files that actually exist under `technical-guidelines/`.
 - A row in this index activates a known guideline type for bootstrap, refresh, and parity behavior.
-- If no starter template file exists for a listed guideline type, use the stable guideline headings from the contract.
+- If no starter template file exists for a listed guideline type, use the Stable Headings schema defined below.
 - Update the relevant row whenever a guideline changes owner, scope, or review trigger.
 - Cross-reference owning project docs such as `architecture.md` or `testing.md` when a guideline depends on them.
 
-## 5. Stable Headings
-New guideline files must include the standard numbered headings below to keep all rulebooks consistent. Feel free to add extra domain-specific headings if needed.
+## 9. Guideline Stable Headings
+New guideline files must include the standard numbered headings below to keep all rulebooks consistent. When documenting a guideline, both developers and AI agents are **NOT** limited to this baseline schema; they must actively append additional, custom domain-specific headings (for example, under Section 3 or as subheadings) to capture the unique technical standards, tooling, and constraints of the codebase.
 
 1. **`## 1. Summary`**: A brief overview of what rules this guideline documents.
 2. **`## 2. Scope`**: The explicit boundaries of what these rules cover (and don't cover).
 3. **`## 3. Rules`**: The hard rules that must be followed.
 4. **`## 4. Preferred Patterns`**: Examples or guidelines of the *best* way to do something.
 5. **`## 5. Anti-Patterns`**: Examples of what *not* to do.
-6. **`## 6. Related Docs`**: Links to `technical/` docs or other guidelines.
+6. **`## 6. Related Docs`**: Links to active core project documents or other guidelines.
 7. **`## 7. Open Questions`**: Any unresolved rules or edge cases.
+
+## 10. Success Metrics
+AI agents and developers can easily reference, follow, and validate cross-cutting code standard compliance during changes.
+
+## 11. Related Documents
+- [Master Project Registry](../index.md) - The active document catalog.
+
+## 12. Open Questions
+None.

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

@@ -3,55 +3,38 @@
 Generate the **initial project documentation set** for a repository. 
 You must dynamically adjust your behavior based on the current state of the repository.
 
-## State Detection (Universal Document Handler)
-Before writing any documents, analyze the workspace to determine its state:
-1. **Zero Docs (Fresh Repo):** No existing documentation and no code. You must ask the user questions to build the specifications from scratch.
-2. **Unclear Docs (Running Repo):** Code exists but docs are missing or outdated. Analyze the existing codebase (package files, database schemas, api routes) to reverse-engineer `foundation/architecture.md` and `technical/database.md`. Ask the user to fill in the missing product goals.
-3. **Mature Docs:** Existing legacy documentation exists but isn't in the EHA format. Map the existing docs into the new 4-layer taxonomy `docs/project-docs/` format without losing historical context.
-
-## Required Behavior
-1. Follow the 4-layer file structure defined in the EHA Project Doc Rules above (`foundation/`, `operations/`, `technical/`, `technical-guidelines/`).
+## Step 1: State & Complexity Detection (The Adaptive Taxonomy)
+Before writing any documents, analyze the workspace to determine its state (Zero Docs vs. Unclear Docs vs. Mature Docs) and its complexity. 
+
+Based on the repository's complexity, you MUST recommend one of the following **Taxonomy Tiers**:
+
+1. **Tier 1: Lite Profile** 
+   - *Target:* Small scripts, micro-libraries, single-component repos.
+   - *Files Generated:* `index.md`, `getting-started.md`, `foundation/prd.md`, `foundation/architecture.md`, `foundation/status.md`.
+2. **Tier 2: Standard Profile**
+   - *Target:* Typical web applications, APIs, standard services.
+   - *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`.
+
+**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.
+
+## Step 2: Document Generation
+Once the user approves a tier, strictly follow the 4-layer file structure (`foundation/`, `operations/`, `development/`, `technical-guidelines/`).
+
+### Required Behavior
+1. **Dynamic Generation from Registry:** You MUST read the master registry file `docs/templates/project-docs-template/index.md` to obtain the universal stable headings schema and the unique domain-specific headings for each document type within the approved tier. Generate each document dynamically using this structural mapping.
 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.
-
-## Output Contract (The Massive Document Structure)
-Create these files under `docs/project-docs/`. If you lack the context to fill them out, generate the markdown headings and mark the content as TBD.
-
-**Root:**
-- `index.md`
-- `getting-started.md`
-
-**Foundation:**
-- `foundation/prd.md`
-- `foundation/architecture.md`
-- `foundation/workflow.md`
-- `foundation/status.md`
-- `foundation/phases.md`
-- `foundation/changelog.md`
-- `foundation/feature-inventory.md`
-
-**Operations:**
-- `operations/ci-cd.md`
-- `operations/production-runbook.md`
-- `operations/governance.md`
-- `operations/compliance.md`
-- `operations/observability.md`
-- `operations/security.md`
-
-**Technical:**
-- `technical/testing.md`
-- `technical/api-contract.md`
-- `technical/database.md`
-- `technical/ui-ux.md`
-- `technical/error-handling.md`
-- `technical/internationalization.md`
+5. **DO NOT generate files outside the approved tier.**
 
 ## 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 `technical/testing.md` do not conflict.
-3. The generated documents strictly follow the Flexible Baselines principle (you may omit heavily specialized docs if the user confirms they aren't needed).
+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.
 
 ## Inputs
-Use the project brief, codebase, and constraints provided below to begin generation.
+Use the project brief, codebase, and constraints provided below to begin your Phase 1 analysis.

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

@@ -42,7 +42,7 @@ Check at least these areas when present:
 3. Treat `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` as the authoritative inventories for optional regular docs and guideline docs when present.
 4. Treat clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/` as migration input only, not as owner-doc paths.
 5. 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.
-6. 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/`.
+6. 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/`.
 7. Distinguish between:
    - true contradiction
    - stale summary

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

@@ -43,19 +43,21 @@ Update **only the docs that own the changed information** while keeping the docu
 
 ## Ownership Examples
 
-- stack or dependency changes → `foundation/architecture.md`, `technical/testing.md`
-- feature scope changes → `foundation/prd.md`, `foundation/feature-inventory.md`, `foundation/status.md`
+- 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/index.md`, workflow docs if present
-- validation / CI changes → `technical/testing.md`, `getting-started.md`
-- production environment, rollout, rollback, or smoke-check changes → `operations/production-runbook.md`, `foundation/architecture.md`, `technical/testing.md`
+- workflow or roadmap changes → `foundation/status.md`, `foundation/phases.md`, 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`
+- security or compliance changes → `operations/security-compliance.md`
+- observability, logging, or error-handling changes → `operations/observability-error-handling.md`
 - 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/` 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.md` 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/index.md`, the relevant phase or epic docs, `foundation/status.md`, and `docs/project-docs/index.md`
+- legacy phased-planning promotion → `docs/project-docs/foundation/phases.md`, `foundation/status.md`, and `docs/project-docs/index.md`
 
 ## Output Contract
 

package/docs/templates/reusable-prompts/01-sdd-execute.md

@@ -31,4 +31,4 @@ Translate a newly updated project specification into tested, working code by fol
 - The user's prompt requesting the execution of a feature.
 - `docs/project-docs/foundation/prd.md`
 - `docs/project-docs/foundation/architecture.md`
-- `docs/project-docs/technical/testing.md`
+- `docs/project-docs/development/testing.md`

package/docs/templates/reusable-prompts/02-sdd-discuss.md

@@ -12,7 +12,7 @@ Act as a Senior Engineer / Agile Product Manager to help the user brainstorm and
    - API shapes and payload structures.
    - UI/UX constraints or responsive layouts.
    - Data model changes (new tables, columns, relations).
-3. **Draft the Spec:** Once the user answers your questions and you reach an agreement, output a drafted, markdown-formatted snippet that is ready to be injected into the specific target documents (e.g., `foundation/prd.md`, `foundation/architecture.md`, `technical/api-contract.md`).
+3. **Draft the Spec:** Once the user answers your questions and you reach an agreement, output a drafted, markdown-formatted snippet that is ready to be injected into the specific target documents (e.g., `foundation/prd.md`, `foundation/architecture.md`, `development/api-contract.md`).
 4. **Final Approval:** Ask the user: "Should I execute the SDD workflow (`01-sdd-execute.md`) with these specifications?"
 
 ## Output Contract