@sallmarta/eye-hate-agent 1.0.3 → 1.0.4

package/docs/templates/skills/{auditing/parity → parity-audit}/SKILL.md

@@ -1,17 +1,15 @@
 ---
-name: parity
+name: "parity-audit"
 description: "Expert-role parity check across project docs, platform instruction surfaces, skills, reusable prompts, workflows, quick-reference material, and implementation evidence when authority depends on the current codebase. Use when checking whether the template system still agrees with itself or when preparing cleanup after major changes."
 argument-hint: "Describe the scope to audit: full repository, docs only, reusable prompt system, platform instruction surfaces and skills, or a specific workstream"
 ---
 
-# Parity — Project-Aware
+# Parity Audit
 
-Performs an **expert repository-wide drift audit** to find contradictions, stale summaries, duplicated ownership, code-vs-doc authority conflicts, and historical artifacts that should be classified rather than confused with active truth.
+Performs an expert repository-wide drift audit to find contradictions, stale summaries, duplicated ownership, code-vs-doc authority conflicts, and historical artifacts that should be classified rather than confused with active truth.
 
 This skill is the reusable complement to the parity reusable prompt. Use it when the task is analytical rather than generative.
 
----
-
 ## Required Project Inputs
 
 | Document | Why it matters |
@@ -19,16 +17,14 @@ This skill is the reusable complement to the parity reusable prompt. Use it when
 | EHA Rules | Ownership map and canonical doc taxonomy |
 | `docs/project-docs/foundation/prd.md` | Active project identity and scope |
 | `docs/project-docs/foundation/architecture.md` | Active stack and architecture truth |
-| `docs/project-docs/technical/testing.md` | Active verification truth |
+| `docs/project-docs/development/testing.md` | Active verification truth |
 | `docs/project-docs/foundation/status.md` | Active roadmap and current-state truth |
 | Platform instruction surfaces | Automatic behavior layer |
 | Skills and reusable prompts | Reusable procedure and generation layers |
 | Workflow, handoff, and historical docs | Potentially valid references or stale artifacts |
 | Relevant code, tests, configs, and runtime-facing artifacts | Evidence for whether active docs still match the current repository |
 
----
-
-## When To Use
+## When to Use
 
 | Trigger | Example request |
 | --- | --- |
@@ -37,10 +33,6 @@ This skill is the reusable complement to the parity reusable prompt. Use it when
 | Template maintenance | "Audit platform instruction surfaces and skills after changing the contract" |
 | Handoff preparation | "Find contradictions before handing this repo to another maintainer" |
 
-Use `full-verification` instead when the user asks for a broad verification entry point and repository drift is only one possible verification path.
-
-Typical audit targets include:
-
 Check for disagreement across:
 
 - project identity and naming
@@ -53,8 +45,6 @@ Check for disagreement across:
 - rule expectations vs documented workflow
 - active docs vs current code, tests, configs, or runtime-facing behavior when authority is disputed
 
----
-
 ## Procedure
 
 ### Step 1 — Establish the source of truth
@@ -99,29 +89,7 @@ Determine whether the mismatch affects:
 
 Recommend which owning file or layer should be updated. Do not spread the same fact across more files than necessary.
 
----
-
-## Output Contract
-
-For each finding, include:
-
-1. severity
-2. fact in conflict
-3. source-of-truth location
-4. conflicting location
-5. classification
-6. why it matters
-7. recommended owner to update
-8. whether user direction is required before deciding the fix path
-
-End with:
-
-1. highest-priority drift items
-2. acceptable historical artifacts that should not be treated as blockers
-
----
-
-## Quality Checks
+## Quality Check
 
 - Do not confuse reference material with active truth
 - Do not propose fixing both sides of a contradiction when one side clearly owns the fact
@@ -129,9 +97,7 @@ End with:
 - Keep the audit actionable, not just descriptive
 - Do not assume docs or code win when authority for the disputed fact is not explicit
 
----
-
-## Anti-Patterns
+## Anti-Pattern
 
 - Treating summary files as the owner when the contract defines a different source of truth
 - Reporting drift without naming the owning file or layer that should change
@@ -139,20 +105,28 @@ End with:
 - Duplicating the same fact across multiple layers as a fix for drift
 - Assuming implementation drift or documentation drift without checking whether the repository defines authority for that fact
 
----
+## Output Contract
 
-## Natural Prompt Shapes
+For each finding, include:
 
-- "Check whether the docs and repository still agree."
-- "Audit this repo for drift after the latest changes."
-- "Find contradictions across docs, platform instruction surfaces, skills, and prompts."
-- "Tell me which mismatches are real blockers versus harmless leftovers."
+1. severity
+2. fact in conflict
+3. source-of-truth location
+4. conflicting location
+5. classification
+6. why it matters
+7. recommended owner to update
+8. whether user direction is required before deciding the fix path
 
----
+End with:
+1. highest-priority drift items
+2. acceptable historical artifacts that should not be treated as blockers
 
-## Example Requests
+## Neutral Prompt Shape
+`@agent use parity-audit on [Target Scope/Repo] focusing on [Specific Conflicts/Docs].`
 
+## Example Prompt
 - "Audit the repository for contradictions after the latest template changes"
 - "Check whether reusable prompts and skills still match the contract"
 - "Find stale summaries in the project docs"
-- "Classify which mismatches are blockers versus historical artifacts"
+- "Classify which mismatches are blockers versus historical artifacts"

package/docs/templates/skills/refactor/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: "refactor"
+description: "Project-aware expert-role for code refactoring. Reads project docs first, enforces TDD, and restructures code to reduce cyclomatic complexity and improve maintainability without altering external behavior."
+argument-hint: "Describe the function, file, or module to refactor"
+---
+
+# Refactor
+
+Produces a project-aware, expert-level refactoring plan and execution by reading the repository's project docs first, then applying strict structural improvements.
+
+This skill is reusable across any programming language. It focuses on reducing technical debt, splitting monolithic structures, and improving testability. It should not assume a specific framework or design pattern until the project docs confirm them.
+
+## Required Project Inputs
+
+| Document | Why it matters |
+| --- | --- |
+| `docs/project-docs/foundation/architecture.md` | Defines the acceptable patterns, boundaries, and coupling rules for the project. |
+| `docs/project-docs/development/testing.md` | Defines the required testing frameworks and test coverage expectations. |
+| `docs/project-docs/technical-guidelines/index.md` | Provides language-specific linting, style, or idiom rules. |
+
+If the repository lacks the testing docs needed for safe refactoring, call that out and create or update the missing docs instead of refactoring blindly.
+
+## When to Use
+
+Use this skill when tasked with improving existing code without changing its feature set.
+
+| Boundary type | Typical artifacts |
+| --- | --- |
+| Function / Method | Reducing cyclomatic complexity, extracting pure functions, eliminating nested conditionals. |
+| Class / Module | Applying SOLID principles, injecting dependencies, splitting god classes. |
+| File / Directory | Reorganizing imports, breaking large files into logical cohesive units. |
+| Naming & Style | Standardizing variable names, updating to project idioms. |
+
+## Procedure
+
+### Step 1 — Identify the Architecture Constraints
+Extract from `architecture.md`:
+- Domain boundaries and allowed dependency directions.
+- Prescribed patterns (e.g., Use Repositories for data access, use Services for business logic).
+
+### Step 2 — Read Existing Tests
+Extract from the codebase:
+- Are there existing unit or integration tests for the target code?
+- If NO: **Stop.** You must write tests to establish a baseline before changing any structural code.
+
+### Step 3 — Analyze the Target Code
+Evaluate the target code for:
+- High cyclomatic complexity (too many if/else branches).
+- Side effects hidden within otherwise pure logic.
+- Tight coupling to infrastructure or external dependencies.
+- Duplicated logic.
+
+### Step 4 — Formulate the Refactoring Plan
+Design the new structure:
+- Extract pure functions for testability.
+- Introduce dependency injection where hardcoded dependencies exist.
+- Replace complex conditionals with polymorphism, lookup tables, or guard clauses.
+
+### Step 5 — Test-Driven Execution
+1. Ensure the baseline tests pass.
+2. Apply the refactoring incrementally.
+3. Continuously verify that tests pass after each structural change.
+
+### Step 6 — Preserve Documentation
+Ensure all existing comments and docstrings are preserved unless the new structure explicitly invalidates them. In that case, update them accurately.
+
+## Quality Check
+
+Use this checklist when reviewing refactored code:
+
+- Has the external API or behavior of the function/module changed? (It shouldn't).
+- Is the new code easier to unit test?
+- Were dependency rules from `architecture.md` respected?
+- Were original comments preserved or updated?
+- Did the refactoring introduce any new dependencies?
+
+## Anti-Pattern
+
+- Refactoring code without baseline tests.
+- Over-engineering (e.g., introducing a complex Factory pattern for a simple two-branch conditional).
+- Changing feature behavior or fixing bugs silently during a refactor.
+- Silently deleting developer comments or context notes.
+
+## Output Contract
+
+When using this skill, the output should include:
+
+1. the project docs consulted
+2. the identified code smells / issues in the target code
+3. the baseline testing strategy used
+4. the step-by-step refactoring changes applied
+5. verification that all external behavior remains identical
+
+## Neutral Prompt Shape
+`@agent use refactor on [Target Function/File] focusing on [Specific Architecture/Simplicity Goal].`
+
+## Example Prompt
+- "Refactor this god class into smaller cohesive services."
+- "Reduce the cyclomatic complexity of this function."
+- "Reorganize the imports and structure of this legacy file."

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

@@ -0,0 +1,149 @@
+---
+name: "security-audit"
+description: "Project-aware expert-role for security and vulnerability auditing. Reads project docs first, enforces strict boundary controls, OWASP Top 10 mitigation, authentication, and data privacy rules across the codebase."
+argument-hint: "Point to the code, file, module, or change to audit"
+---
+
+# Security Audit
+
+Produces a project-aware, **expert-level security audit** by reading the repository's project docs first, then applying rigorous threat modeling and vulnerability analysis to the current architecture.
+
+This skill is reusable across application logic, API boundaries, infrastructure configurations, and data persistence layers. It should not assume specific compliance frameworks (like SOC2 or HIPAA) until the project docs explicitly confirm them.
+
+## Required Project Inputs
+
+| Document | Why it matters |
+| --- | --- |
+| `docs/project-docs/operations/security-compliance.md` | Defines the actual threat model, acceptable risk, security gates, PII masking, data retention, and regulatory requirements. |
+| `docs/project-docs/foundation/architecture.md` | Defines trust boundaries, network zones, and where authentication/authorization is enforced. |
+| `docs/project-docs/development/api-contract.md` | Clarifies the expected payload shapes and validation rules to prevent injection attacks. |
+
+If the repository lacks the security docs needed for a proper audit, call that out and establish baseline security assumptions before reviewing code.
+
+## When to Use
+
+Use this skill when tasked with identifying vulnerabilities or ensuring code meets security standards.
+
+| Boundary type | Typical artifacts |
+| --- | --- |
+| Authentication / Authorization | JWT validation, role-based access control (RBAC), session management. |
+| API / Input Validation | Preventing SQL injection, XSS, CSRF, and mass assignment vulnerabilities. |
+| Data Privacy / Cryptography | Encryption at rest/transit, hashing algorithms, secret management. |
+| Infrastructure Security | Dockerfile security, IAM permissions, network exposure. |
+
+## Procedure
+
+### Step 1 — Understand intent
+
+- What is this code supposed to do?
+- What inputs, outputs, and side effects should it have?
+- Which boundary does it sit behind?
+- What project rules apply here?
+
+### Step 2 — Check correctness risks
+
+Look for:
+
+- runtime crashes
+- missing validation
+- broken assumptions around nullability or absence
+- incorrect state transitions
+- failure to handle empty, partial, duplicate, or delayed inputs
+- unsafe retry or transaction behavior
+- concurrency or sequencing defects
+- schema or serialization mismatches
+
+### Step 3 — Check boundary violations
+
+Use `architecture.md` to inspect:
+
+- layer or module import violations
+- leaked internal types across boundaries
+- controllers or UI doing business logic that belongs elsewhere
+- repositories or services depending on the wrong layer
+- transport or persistence details leaking into durable domain concepts when the project forbids that
+- identify where untrusted input enters the system (e.g., public APIs, webhooks, file uploads). 
+- identify where trust is explicitly verified (e.g., API gateways, auth middlewares).
+
+### Step 4 — Audit Authentication and Session State
+Evaluate auth mechanisms against `security-compliance.md`:
+- Are tokens securely stored (e.g., HttpOnly cookies instead of LocalStorage)?
+- Are session timeouts and revocation mechanisms implemented?
+- Is authorization checked on every privileged action, not just at the UI level?
+
+Also look for:
+
+- duplicated logic
+- unused or unreachable branches
+- stale abstractions
+- helper functions with no callers
+- repeated literal values that should be owned centrally
+- duplicated normalization or mapping logic that should be shared
+
+### Step 5 — Check Secret Management and Cryptography
+Ensure: No hardcoded secrets, passwords, or API keys exist in the codebase. Sensitive data is hashed using strong algorithms (e.g., Argon2, bcrypt) with salts. Data in transit is strictly TLS-enforced.
+
+### Step 6 — Verify Compliance and PII Handling
+Consult `security-compliance.md`: Ensure PII is not leaked into application logs, error messages, or third-party analytics tools. Verify data retention constraints are implemented.
+
+### Step 7 — Prioritize findings
+
+Classify findings by severity:
+
+- critical
+- high
+- medium
+- low
+
+Each finding should include:
+
+- location
+- issue
+- why it matters
+- concrete corrective direction
+
+## Quality Check
+
+- Are all inputs crossing a trust boundary rigorously validated?
+- Are secrets injected via environment variables rather than hardcoded?
+- Are dependencies checked for known CVEs?
+- Does the code adhere to the Principle of Least Privilege?
+- Are error messages stripped of internal stack traces before returning to the client?
+- 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
+
+- Relying exclusively on client-side validation for security.
+- Concatenating SQL queries with user input.
+- Logging raw request bodies that might contain passwords or PII.
+- Implementing custom cryptography instead of using proven industry standards.
+- Assuming an internal network is completely trustworthy without zero-trust checks.
+- 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
+
+When using this skill, the output should include:
+1. the project docs consulted and assumed threat model
+2. identified vulnerabilities categorized by OWASP standard
+3. severity rating (Critical, High, Medium, Low) for each finding
+4. exploitability and impact analysis
+5. specific, actionable remediation steps for each finding
+
+## Neutral Prompt Shape
+`@agent use security-audit on [Target Component/API] focusing on [Specific Threat/Vulnerability].`
+
+## Example Prompt
+- "Audit this new authentication controller for session management flaws."
+- "Review this file upload endpoint for security risks."
+- "Perform a security audit on this database migration script."
+- "Review this code for bugs, risks, and boundary issues."
+- "Audit this module like a strict senior reviewer."
+- "Check whether this implementation has correctness or security problems."
+- "Find dead code, logic flaws, and maintainability risks in this change."

package/docs/templates/skills/{architecture/system-analysis → system-analysis}/SKILL.md

@@ -1,34 +1,29 @@
 ---
-name: analysis
+name: "system-analysis"
 description: "Project-aware expert-role analysis for architecture, debugging, trade-offs, risk, performance, requirements, and design questions. Reads project docs first, then applies expert structured reasoning to the current repository context."
 argument-hint: "Describe the problem, decision, artifact, or system to analyze"
 ---
 
-# Analysis — Project-Aware
+# System Analysis
 
 Produces a **rigorous, expert-level analysis** of a problem, decision, artifact, or system after first reading the project documentation that defines the repository's actual context.
 
 This skill is reusable across product, backend, frontend, infrastructure, monorepo, and documentation-heavy projects. It should not assume a particular stack until the project docs confirm it.
 
----
-
 ## Required Project Inputs
 
 | Document | Why it matters |
 | --- | --- |
-
 | `docs/project-docs/foundation/prd.md` | Clarifies goals, scope, stakeholders, and success metrics |
 | `docs/project-docs/foundation/architecture.md` | Defines stack, boundaries, integration model, constraints, and runtime assumptions |
 | `docs/project-docs/foundation/status.md` | Reveals maturity, roadmap, active workstreams, and known blockers |
-| `docs/project-docs/technical/testing.md` | Shows what validation exists and how strong the available evidence can be |
+| `docs/project-docs/development/testing.md` | Shows what validation exists and how strong the available evidence can be |
 | Relevant feature, workflow, API, or guideline docs | Supply domain-specific truth for the topic being analyzed |
 | Relevant code, logs, tests, or runtime evidence | Support findings with direct evidence rather than guesswork |
 
 If the required project docs are missing, note the gap explicitly and limit confidence accordingly.
 
----
-
-## When To Use
+## When to Use
 
 | Trigger | Example request |
 | --- | --- |
@@ -40,8 +35,6 @@ If the required project docs are missing, note the gap explicitly and limit conf
 | Performance diagnosis | "Analyze where this request path will bottleneck" |
 | Product or roadmap question | "Analyze whether this feature belongs in MVP" |
 
----
-
 ## Procedure
 
 ### Step 1 — Understand the question
@@ -121,22 +114,7 @@ When comparing options or hypotheses:
 - say what could change the conclusion
 - tie the recommendation back to the project's actual constraints
 
----
-
-## Output Contract
-
-Your output should include:
-
-1. summary
-2. analysis by area or component
-3. key findings ordered by importance
-4. recommendation or decision guidance
-5. risks and open questions
-6. confidence and evidence limitations when relevant
-
----
-
-## Quality Checks
+## Quality Check
 
 - No claim without evidence or clearly marked assumption
 - No false precision when evidence is weak
@@ -144,9 +122,7 @@ Your output should include:
 - No vague recommendation without an actionable next step
 - No hidden stack assumptions that were not confirmed from project docs
 
----
-
-## Anti-Patterns
+## Anti-Pattern
 
 - Listing facts without evaluating them
 - Jumping to the first plausible conclusion
@@ -154,20 +130,22 @@ Your output should include:
 - Recommending a rewrite when an incremental fix would solve the problem
 - Ignoring the project stage, roadmap, or non-goals in `prd.md` and `status.md`
 
----
-
-## Natural Prompt Shapes
+## Output Contract
 
-- "Why is this failing, and what do you think is the real cause?"
-- "Analyze this decision and tell me whether it still makes sense."
-- "What are the trade-offs and risks of these two options?"
-- "Check whether these requirements or assumptions still hold up."
+When using this skill, the output should include:
 
----
+1. summary
+2. analysis by area or component
+3. key findings ordered by importance
+4. recommendation or decision guidance
+5. risks and open questions
+6. confidence and evidence limitations when relevant
 
-## Example Requests
+## Neutral Prompt Shape
+`@agent use system-analysis on [Target Directory/Component] focusing on [Specific Goal/Flow].`
 
+## Example Prompt
+- "Analyze this decision and tell me whether it still makes sense."
 - "Analyze this module boundary for coupling risk"
 - "Analyze why this workflow fails intermittently"
-- "Analyze option A vs option B for this integration"
-- "Analyze whether this feature belongs in MVP"
+- "Analyze option A vs option B for this integration"