@sallmarta/eye-hate-agent 1.0.2 → 1.0.4

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

@@ -0,0 +1,40 @@
+# Project Docs Bootstrap Reusable Prompt
+
+Generate the **initial project documentation set** for a repository. 
+You must dynamically adjust your behavior based on the current state of the repository.
+
+## 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.
+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 `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 your Phase 1 analysis.

package/docs/{vibes → templates}/reusable-prompts/00-project-docs-parity.md

@@ -1,7 +1,5 @@
 # Project Docs Parity Reusable Prompt
 
-Read `docs/eyehateagent-contract.md` first.
-
 Audit the repository for **documentation-system drift**.
 
 ## Goal
@@ -18,8 +16,8 @@ Check at least these areas when present:
 - relevant code, tests, configs, or runtime-facing artifacts when a finding depends on current implementation behavior or source-of-truth ownership
 - clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/`
 - platform instruction surfaces (mirrored rule files)
-- `docs/vibes/skills/`
-- `docs/vibes/reusable-prompts/`
+- `docs/templates/skills/`
+- `docs/templates/reusable-prompts/`
 - workflow docs and handoff docs
 
 ### High-Value Drift Categories
@@ -40,11 +38,11 @@ Check at least these areas when present:
 ## Required Behavior
 
 1. Use project docs as the primary source of truth for documentation ownership and doc-to-doc drift unless the repository explicitly states otherwise.
-2. Treat `docs/eyehateagent-contract.md` as the ownership map.
+2. Use the EHA Project Doc Rules above as the ownership map.
 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/{vibes → templates}/reusable-prompts/00-project-docs-refresh.md

@@ -1,7 +1,5 @@
 # Project Docs Refresh Reusable Prompt
 
-Read `docs/eyehateagent-contract.md` first.
-
 Refresh the existing project documentation after a change in scope, stack, workflow, architecture, testing policy, or product behavior.
 
 ## Goal
@@ -11,7 +9,7 @@ Update **only the docs that own the changed information** while keeping the docu
 ## Required Behavior
 
 1. Read the current project docs before editing anything.
-2. Use `docs/eyehateagent-contract.md` to identify which files own the changed information.
+2. Use the EHA Project Doc Rules above to identify which files own the changed information.
 3. Read `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` when present and treat them as the authoritative inventories for optional docs and guideline docs.
 4. When clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/` exist, read them as migration input only and do not treat them as owner-doc paths.
 5. Update only the affected docs and any documents that summarize them.
@@ -45,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
 
@@ -72,7 +72,7 @@ Your result should state:
 
 Before finishing, check that:
 
-1. the updated docs still match the contract in `docs/eyehateagent-contract.md`
+1. the updated docs still match the EHA Project Doc Rules above
 2. platform instruction surfaces and skills would now read the correct project-specific truth
 3. no stale summary remains in `foundation/status.md`, `docs/project-docs/index.md`, `technical-guidelines/index.md`, or other index docs
 

package/docs/{vibes → 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/{vibes → 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
@@ -23,5 +23,5 @@ Act as a Senior Engineer / Agile Product Manager to help the user brainstorm and
 ## Inputs
 
 - The user's rough feature idea or concept.
-- `docs/project-docs/foundation/prd.md` (to understand current scope)
-- `docs/project-docs/foundation/architecture.md` (to understand current stack constraints)
+- Read `docs/project-docs/foundation/prd.md` if it exists (to understand current scope).
+- Read `docs/project-docs/foundation/architecture.md` if it exists (to understand current stack constraints).

package/{.agents/rules/agent.md → docs/templates/rules/agent-rules.md}

@@ -1,11 +1,3 @@
----
-trigger: always_on
----
-
----
-description: "Lean always-on rules for guardrails, context, intake, verification, and doc sync."
----
-
 # Agent Rules
 
 ## 1. Guardrails & Approach
@@ -22,7 +14,10 @@ Protect the prompt prefix cache and manage context-window capacity to preserve t
 
 - **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 Stability (Gemini):** Never reorder tool definitions, system instructions, or serialized schemas mid-session — the implicit prefix cache requires a byte-identical prompt prefix for the 90% cached-token discount. Do not inject dynamic content (timestamps, session IDs, reordered JSON keys) before or between stable blocks. Append all per-turn dynamic data after the stable prefix. If cache-hit rates drop unexpectedly, suspect non-deterministic serialization or framework-injected metadata before other causes.
+- **2.3** **Agent-Specific Cache Strategies:**
+  - **Claude (Prefix & Lookback Integrity):** 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. In heavy agentic loops, be aware of the ~20-block lookback window; explicitly request the user to perform a minor conversational interaction to prevent silent cache misses.
+  - **Antigravity (Prefix Stability):** Never reorder tool definitions, system instructions, or serialized schemas mid-session. The implicit prefix cache requires a byte-identical prompt prefix for the 90% cached-token discount. Append all per-turn dynamic data after the stable prefix. If cache-hit rates drop unexpectedly, suspect non-deterministic serialization.
+  - **Copilot (Context Efficiency):** 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.
 - **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
@@ -37,7 +32,7 @@ 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** Skip the intake checklist only for trivial single-step edits.
+- **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.
 
 ## 4. Docs, Verification, and Completion
 
@@ -58,9 +53,9 @@ Embed the critical behavioral rules from the contract so agents follow them with
 - **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/`.
+  3. The active EHA rules 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.
+- **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/docs/{vibes → templates}/skills/api-design/SKILL.md

@@ -4,7 +4,7 @@ description: "Project-aware expert-role contract design for APIs, interfaces, re
 argument-hint: "Describe the boundary, interface, endpoint, message contract, or service behavior to design or review"
 ---
 
-# Interface & API Contract Design — Project-Aware
+# API Design
 
 Produces a **project-aware, expert-level contract design or design review** by reading the repository's project docs first, then applying a reusable method to the current boundary type.
 
@@ -19,23 +19,18 @@ This skill is intentionally reusable across:
 
 It should **not** assume one language, framework, transport, or architecture style until the project docs confirm them.
 
----
-
 ## Required Project Inputs
 
 | Document | Why it matters |
 | --- | --- |
-
 | `docs/project-docs/foundation/architecture.md` | Defines stack, architecture boundaries, dependency rules, and integration patterns |
 | `docs/project-docs/foundation/prd.md` | Clarifies scope, constraints, stakeholders, and non-goals |
-| `docs/project-docs/technical/testing.md` | Defines how the contract should be validated |
+| `docs/project-docs/development/testing.md` | Defines how the contract should be validated |
 | Relevant feature docs, API docs, or guidelines | Provide domain-specific rules, request/response shapes, workflows, and edge cases |
 | Existing code or contracts in the repo | Show local naming, layering, serialization, validation, and error conventions |
 
 If the repository lacks the contract-defining docs needed for the task, call that out and create or update the missing docs instead of inventing local rules in the skill.
 
----
-
 ## When To Use
 
 Use this skill when designing or reviewing one of these boundary types.
@@ -49,8 +44,6 @@ Use this skill when designing or reviewing one of these boundary types.
 | Event or message contract | payload schema, producer/consumer expectations, ordering, retry, dead-letter rules |
 | Module boundary | public interface, dependency direction, allowed imports, extension points |
 
----
-
 ## Procedure
 
 ### Step 1 — Identify the contract owner
@@ -141,8 +134,6 @@ Examples:
 
 The output should fit the repository style and include enough detail to implement safely without locking the repo into one stack-specific pattern that the docs do not support.
 
----
-
 ## Output Contract
 
 When using this skill, the output should include:
@@ -155,8 +146,6 @@ When using this skill, the output should include:
 6. verification strategy
 7. open questions that still require product or architecture decisions
 
----
-
 ## Quality Checks
 
 Use this checklist when reviewing an existing contract:
@@ -169,8 +158,6 @@ Use this checklist when reviewing an existing contract:
 - Does the contract create hidden coupling or leak implementation details?
 - Is there a clear verification strategy in `testing.md`?
 
----
-
 ## Anti-Patterns
 
 - Embedding one stack's rules into the skill instead of reading project docs
@@ -180,19 +167,21 @@ Use this checklist when reviewing an existing contract:
 - Ignoring versioning, compatibility, or migration concerns for externally visible contracts
 - Over-designing the contract far beyond the current scope in `prd.md`
 
----
-
-## Natural Prompt Shapes
-
-- "Design the contract for this API or service boundary."
-- "Check whether this endpoint or DTO shape is designed correctly."
-- "Define the interface, error contract, and validation rules for this boundary."
-- "Review whether this event or repository contract matches the architecture."
+## Output Contract
 
----
+When using this skill, the output should include:
+1. the boundary type
+2. the project docs consulted
+3. the proposed contract shape
+4. validation and error rules
+5. ownership and dependency implications
+6. verification strategy
+7. open questions that still require product or architecture decisions
 
-## Example Requests
+## Neutral Prompt Shape
+`@agent use api-design on [Target Entity/Feature] focusing on [Specific Constraints/Version].`
 
+## Example Prompt
 - "Design the repository contract for this feature"
 - "Review this controller and DTO boundary"
 - "Design an event payload for this workflow"

package/docs/{vibes/skills/full-verification → templates/skills/code-audit}/SKILL.md

@@ -1,37 +1,32 @@
 ---
-name: full-verification
+name: "code-audit"
 description: "Project-aware expert-role broad verification that reads project docs first, classifies the verification target, and routes to the best specialist skill for executable or non-executable checks across code, contracts, docs, architecture, quality, security, reliability, and project health."
 argument-hint: "Describe what should be verified against the contract, project docs, guidelines, code, APIs, architecture, or repository state"
 ---
 
-# Full Verification — Project-Aware
+# Code Audit
 
 Provides an **expert, project-aware broad verification entry point** for requests that ask whether something is correct, consistent, healthy, complete, or aligned with the repository's contract and project docs.
 
 This skill is **routing-first**. Its primary job is to identify the dominant verification question and route to the single best specialist skill rather than duplicating every verification procedure itself.
 
-This skill is intentionally **not tied to any single stack or framework**. When executable checks are needed, it should select the correct framework, commands, and conventions from the project's `technical/testing.md`, `foundation/architecture.md`, and local repository patterns.
-
----
+This skill is intentionally **not tied to any single stack or framework**. When executable checks are needed, it should select the correct framework, commands, and conventions from the project's `development/testing.md`, `foundation/architecture.md`, and local repository patterns.
 
 ## Required Project Inputs
 
 | Document | Why it matters |
 | --- | --- |
-| `docs/eyehateagent-contract.md` | Defines routing, ownership, precedence, and the active skill model |
-
-| `docs/project-docs/technical/testing.md` | Defines executable and non-executable verification rules, commands, and fallback policy |
-| `docs/project-docs/foundation/architecture.md` | Defines boundaries, stack, interfaces, dependency rules, and runtime assumptions |
-| `docs/project-docs/foundation/prd.md` | Defines goals, scope, non-goals, and success criteria |
+| EHA Rules | Defines routing, ownership, precedence, and the active skill model |
+| `docs/project-docs/foundation/architecture.md` | Defines boundaries, dependencies, stack choices, and anti-violation rules |
+| `docs/project-docs/development/testing.md` | Defines available validation and evidence strength |
+| `docs/project-docs/foundation/prd.md` | Clarifies scope, non-goals, and project stage |
 | `docs/project-docs/foundation/status.md` | Defines maturity, roadmap, active workstreams, and readiness context |
 | Relevant guideline docs under `docs/project-docs/technical-guidelines/` | Define technical standards such as API, logging, database, error-handling, code style, or design patterns |
 | Relevant code, tests, docs, contracts, and repository artifacts | Provide the actual evidence surfaces to verify against |
 
 If required project docs are missing, surface that gap explicitly and limit confidence rather than guessing.
 
----
-
-## When To Use
+## When to Use
 
 | Trigger | Example request |
 | --- | --- |
@@ -43,15 +38,12 @@ If required project docs are missing, surface that gap explicitly and limit conf
 
 Use a specialist skill directly when the dominant question is already obvious:
 
-- `test-authoring` for executable verification strategy, stack-aware test selection, and test-writing decisions
+- `system-tester` for executable verification strategy, stack-aware test selection, and test-writing decisions
 - `code-audit` for code correctness, bug, risk, security, and boundary review
-- `parity` for repository drift across docs, platform instruction surfaces, skills, prompts, and summaries
-- `project-elevation` for forward-looking improvement and readiness planning
-- `analysis` for root-cause reasoning, trade-off evaluation, and requirement or decision analysis
+- `parity-audit` for repository drift across docs, platform instruction surfaces, skills, prompts, and summaries
+- `system-analysis` for root-cause reasoning, trade-off evaluation, and requirement or decision analysis
 - `api-design` for API, schema, interface, or boundary contract design and review
 
----
-
 ## Procedure
 
 ### Step 1 — Identify the verification target
@@ -86,12 +78,11 @@ Prefer the single strongest verification path unless the user explicitly asks fo
 
 | Dominant verification question | Route to |
 | --- | --- |
-| How should this be verified, tested, or regression-checked in the current stack? | `test-authoring` |
+| How should this be verified, tested, or regression-checked in the current stack? | `system-tester` |
 | Is this code correct, safe, consistent, and free of obvious bugs or boundary violations? | `code-audit` |
 | Does this API or interface contract match the docs, code, and boundary rules? | `api-design` |
-| Do the docs, platform instruction surfaces, skills, prompts, and repository artifacts still agree? | `parity` |
-| What should improve next, and how healthy or mature is this project at its current stage? | `project-elevation` |
-| Do the requirements, trade-offs, design decisions, or explanations hold up? | `analysis` |
+| Do the docs, platform instruction surfaces, skills, prompts, and repository artifacts still agree? | `parity-audit` |
+| Do the requirements, trade-offs, design decisions, or explanations hold up? | `system-analysis` |
 
 Example prompt shapes by verification category:
 
@@ -108,7 +99,7 @@ Example prompt shapes by verification category:
 
 When executable validation is required, choose the appropriate framework and commands from project docs and local repo conventions.
 
-Examples of the decision pattern:
+**Examples** of the decision pattern:
 
 - Go project -> use the Go testing approach documented in `testing.md`
 - Python project -> use the Python testing approach documented in `testing.md`
@@ -126,7 +117,20 @@ State:
 - what evidence and checks should be used
 - what remains outside the chosen verification path
 
----
+## Quality Check
+
+- No finding without evidence from the target artifact
+- No severity inflation
+- No style nitpicks disguised as bugs
+- No architecture complaint without reference to actual project boundaries
+- No recommendation that ignores project stage or available validation
+
+## Anti-Pattern
+
+- Calling something dead code without checking workspace usage
+- Calling something a bug without defining the failure condition
+- Criticizing a pattern that the project explicitly chose in `architecture.md`
+- Recommending wide rewrites before testing a local fix or a smaller boundary change
 
 ## Output Contract
 
@@ -141,33 +145,11 @@ When using this skill, the output should include:
 7. any residual risks or uncovered verification areas
 8. whether user direction is required before deciding between conflicting docs and implementation
 
----
-
-## Quality Checks
-
-- Route to the single best specialist skill unless the user explicitly asks for a broader sweep
-- Do not duplicate another skill's full procedure inside this skill
-- Do not assume frameworks or commands before checking the project docs
-- Keep executable and non-executable verification clearly separated
-- State when confidence is limited by missing docs or missing evidence
-- Do not assume docs or implementation win when the repository does not define authority for the disputed fact
-
----
-
-## Anti-Patterns
-
-- Treating verification as synonymous with writing tests
-- Hardcoding stack-specific frameworks into the skill text
-- Routing a docs-drift problem to `code-audit`
-- Routing a forward-looking improvement question to `analysis`
-- Running a multi-skill sweep by default when one dominant verification path would answer the request
-- Claiming the repository passed a check when the relevant evidence or command was never examined
-
----
-
-## Example Requests
+## Neutral Prompt Shape
+`@agent use code-audit on [Target File/Change] focusing on [Specific Risks/Boundaries].`
 
-- "Verify this feature against the project docs, contract, and actual code"
-- "Check whether this API matches the docs, code, and guideline standards"
-- "Evaluate this project for health, maturity, architecture drift, and consistency"
-- "Use the right verification approach for this stack and tell me what to run"
+## Example Prompt
+- "Audit this service for boundary violations"
+- "Review this change for correctness risks"
+- "Check this module for dead code and duplication"
+- "Audit this workflow implementation for operability gaps"

package/docs/templates/skills/db-schema-design/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: "db-schema-design"
+description: "Project-aware expert-role database schema and modeling design. Reads project docs first, then produces a schema design, migration plan, or query optimization strategy consistent with the current repository constraints."
+argument-hint: "Describe the domain entities, tables, relationships, or queries to design or review"
+---
+
+# Database Schema Design
+
+Produces a **project-aware, expert-level database schema design or review** by reading the repository's project docs first, then applying a rigorous data modeling method.
+
+This skill is reusable across:
+
+- Relational Databases (PostgreSQL, MySQL, Aurora, etc)
+- Document / NoSQL Databases (MongoDB, DynamoDB, etc)
+- In-memory / Cache Models (Redis, Memcache, etc)
+- Event Stores (Kafka, Pulsar, etc)
+
+It should **not** assume a specific database engine, ORM, or normalization strategy until the project docs confirm them.
+
+## Required Project Inputs
+
+| Document | Why it matters |
+| --- | --- |
+| `docs/project-docs/development/database.md` | Defines the actual database engines, ORMs, migration tools, naming conventions, and constraints. |
+| `docs/project-docs/foundation/architecture.md` | Defines where data logic lives (e.g., repository layer) and integration boundaries. |
+| `docs/project-docs/foundation/prd.md` | Clarifies the feature scale, expected data volume, and access patterns. |
+| `docs/project-docs/development/testing.md` | Defines how data layer code and migrations should be validated. |
+
+If the repository lacks the database docs needed for the task, call that out and create or update the missing docs instead of inventing local rules in the skill.
+
+## When to Use
+
+Use this skill when designing or reviewing one of these boundary types:
+
+| Boundary type | Typical artifacts |
+| --- | --- |
+| Schema Creation | Tables, columns, types, constraints, foreign keys, indexes |
+| Migrations | Up/Down migration scripts, data backfills, zero-downtime strategies |
+| Query Optimization | EXPLAIN plans, index selection, join reduction |
+| Data Modeling | Domain entities, aggregates, document embedding vs referencing |
+| Caching | Cache keys, TTL strategies, eviction policies |
+
+## Procedure
+
+### Step 1 — Identify the Engine and Tools
+Extract from `database.md`:
+- the primary database engine (e.g., Postgres 15)
+- the schema management/migration tool (e.g., Prisma, Flyway, Alembic)
+- the application access pattern (raw SQL vs Query Builder vs ORM)
+
+### Step 2 — Identify the Access Patterns
+Extract from `prd.md` and feature docs:
+- Read/Write ratios (is it write-heavy or read-heavy?)
+- Data volume expectations
+- Latency requirements
+- Multi-tenant data segregation rules (if any)
+
+### Step 3 — Design the Schema Shape
+Design the minimal schema that supports the required behavior.
+Specify:
+- Entity names and relationships (1:1, 1:N, M:N)
+- Strict data types (prefer specific types like `UUID` or `TIMESTAMPTZ` over generic strings if the engine supports it)
+- Constraints (NOT NULL, UNIQUE, CHECK)
+- Primary and Foreign keys
+
+### Step 4 — Define Indexing and Performance Strategies
+Define the indexes required for the access patterns identified in Step 2.
+- Consider composite indexes for multi-column queries.
+- Consider partial/filtered indexes for specific status queries.
+- Avoid over-indexing to protect write performance.
+
+### Step 5 — Design the Migration Plan
+Specify how the schema will be deployed safely:
+- Can this be applied without locking tables?
+- Does it require a multi-phase zero-downtime migration (e.g., Add column -> write to both -> backfill -> drop old column)?
+- How will the rollback (down migration) function?
+
+### Step 6 — Define Verification Requirements
+Use `testing.md` to decide how this will be validated.
+Examples:
+- Schema validation tests
+- Query performance benchmarks
+- Migration dry-run tests
+
+## Quality Check
+
+Use this checklist when reviewing an existing schema or PR:
+
+- Does the schema follow the project's naming conventions (e.g., snake_case vs camelCase)?
+- Are foreign keys properly enforcing referential integrity?
+- Are appropriate constraints in place to prevent bad data at the database level?
+- Will the migration lock a critical table in production?
+- Is there a clear separation between the database schema and the application's domain model?
+
+## Anti-Pattern
+
+- Assuming an ORM is used when the project strictly uses raw SQL.
+- Suggesting a heavy relational model for a project that uses a document database.
+- Proposing migrations that lock large tables (e.g., adding a column with a default value in older Postgres versions) without a zero-downtime strategy.
+- Ignoring data types and using strings for dates, JSON, or booleans.
+- Forgetting to define a rollback strategy for a destructive migration.
+
+## Output Contract
+
+When using this skill, the output should include:
+
+1. the database engine and tools being targeted
+2. the project docs consulted
+3. the proposed schema / entity model
+4. indexes and constraints
+5. the migration strategy and risk assessment
+6. verification strategy
+7. open questions regarding data volume or access patterns
+
+## Neutral Prompt Shape
+`@agent use db-schema-design on [Target Feature/Entity] focusing on [Specific Requirement/Database Type].`
+
+## Example Prompt
+- "Design the schema migration for the new order tracking feature."
+- "Optimize the indexing for this query based on read-heavy patterns."