@sallmarta/eye-hate-agent 1.0.2 → 1.0.4

package/docs/templates/skills/devops-ci-cd/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: "devops-ci-cd"
+description: "Project-aware expert-role for CI/CD pipeline design and implementation. Reads project docs first, enforces build caching, security gates, test execution, and deployment safety."
+argument-hint: "Describe the workflow, pipeline, or deployment stage to build or review"
+---
+
+# DevOps CI/CD
+
+Produces a **project-aware, expert-level CI/CD pipeline implementation** by reading the repository's project docs first, then applying robust deployment engineering practices.
+
+This skill is reusable across CI providers (GitHub Actions, GitLab CI, Jenkins) and deployment targets (AWS, GCP, Vercel, Kubernetes).
+
+It should **not** assume a specific CI provider or deployment strategy until the project docs confirm them.
+
+## Required Project Inputs
+
+| Document | Why it matters |
+| --- | --- |
+| `docs/project-docs/operations/ci-cd.md` | Defines the required CI provider, branch protection rules, required jobs, and deployment environments. |
+| `docs/project-docs/development/testing.md` | Defines which test suites must run and their coverage thresholds. |
+| `docs/project-docs/operations/security.md` | Defines required security scanning tools (SAST, DAST, dependency checks). |
+
+If the repository lacks the CI/CD docs needed for deployment, call that out and create or update the missing docs instead of blindly writing deployment scripts.
+
+## When to Use
+
+Use this skill when building or reviewing one of these boundary types.
+
+| Boundary type | Typical artifacts |
+| --- | --- |
+| Continuous Integration (CI) | Build scripts, linter checks, test runners, Docker builds. |
+| Continuous Deployment (CD) | Terraform/Pulumi execution, environment promotion, artifact publishing. |
+| Security & Compliance | Dependabot configuration, secret scanning, static analysis gates. |
+| Pipeline Optimization | Caching strategies, matrix builds, job parallelization. |
+
+## Procedure
+
+### Step 1 — Identify the Pipeline Engine and Target
+Extract from `ci-cd.md`:
+- The CI platform (e.g., GitHub Actions).
+- The deployment target (e.g., AWS ECS).
+- Authentication mechanisms (e.g., OIDC vs long-lived secrets).
+
+### Step 2 — Define the Build Matrix and Caching
+- Ensure language-specific dependencies (node_modules, pip cache, go mod cache) are aggressively cached to reduce build times.
+- If building Docker images, implement layer caching.
+
+### Step 3 — Enforce Testing and Security Gates
+Consult `testing.md` and `security.md`:
+- The pipeline MUST block merges if linters or tests fail.
+- The pipeline MUST block merges if critical security vulnerabilities are detected.
+
+### Step 4 — Implement Safe Deployment Strategies
+If deploying to production:
+- Ensure the pipeline respects environment segregation.
+- Implement rollback capabilities or canary/blue-green deployment steps if specified in `ci-cd.md`.
+- Never hardcode secrets in the pipeline file; always use the CI provider's secrets manager.
+
+### Step 5 — Verify Pipeline Robustness
+Ensure the pipeline:
+- Only triggers on appropriate branches or tags.
+- Has reasonable timeout limits to prevent hung jobs.
+- Cleans up temporary artifacts after execution.
+
+## Quality Check
+
+
+Use this checklist when reviewing an existing CI/CD configuration:
+
+- Are dependencies and build outputs being cached?
+- Are secrets injected securely via environment variables?
+- Does a failing test or linter correctly fail the entire job?
+- Is the deployment step locked down to specific branches or environments?
+- Are timeouts explicitly defined to prevent runaway costs?
+
+## Anti-Pattern
+
+- Hardcoding API keys or passwords directly in the YAML file.
+- Writing a pipeline that deploys to production from any branch.
+- Skipping tests to make the pipeline run faster.
+- Downloading dependencies without verifying lockfiles.
+
+## Output Contract
+
+When using this skill, the output should include:
+
+1. the project docs consulted
+2. the proposed pipeline architecture (triggers, jobs, steps)
+3. the caching and optimization strategies used
+4. the security and testing gates enforced
+5. the final pipeline YAML or script
+
+## Neutral Prompt Shape
+`@agent use devops-ci-cd on [Target Pipeline/Workflow] focusing on [Specific Optimizations/Security Gates].`
+
+## Example Prompt
+- "Create a GitHub Actions workflow that implements the CI caching strategy."
+- "Review this Jenkinsfile for security issues and hardcoded secrets."
+- "Design a deployment pipeline that supports blue-green rollout."

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

@@ -0,0 +1,99 @@
+---
+name: "observability"
+description: "Project-aware expert-role for system observability and SRE engineering. Reads project docs first, enforces structured logging, tracing context injection, PII masking rules, and actionable metric generation."
+argument-hint: "Describe the component, service, or workflow to instrument with observability"
+---
+
+# Observability
+
+Produces a **project-aware, expert-level observability implementation** by reading the repository's project docs first, then applying Site Reliability Engineering (SRE) standards for logging, metrics, and tracing.
+
+This skill is reusable across logging frameworks (Winston, Logback, Zap), tracing standards (OpenTelemetry), and telemetry backends (Prometheus, Datadog, ELK).
+
+It should **not** assume a specific logging library or metric format until the project docs confirm them.
+
+## Required Project Inputs
+
+| Document | Why it matters |
+| --- | --- |
+| `docs/project-docs/operations/observability.md` | Defines the required logging frameworks, metric standards, alerting thresholds, and tracing architectures. |
+| `docs/project-docs/operations/compliance.md` | Defines PII (Personally Identifiable Information) masking and data retention rules. |
+| `docs/project-docs/foundation/architecture.md` | Defines how context (e.g., request IDs, user IDs) flows across service boundaries. |
+
+If the repository lacks the observability docs needed to understand the current stack, call that out and create or update the missing docs instead of inventing arbitrary logging formats.
+
+## When to Use
+
+Use this skill when tasked with improving system visibility or instrumenting code.
+
+| Boundary type | Typical artifacts |
+| --- | --- |
+| Application Logging | Structured JSON logs, error stack traces, context injection. |
+| Distributed Tracing | Spans, span contexts, OpenTelemetry configuration. |
+| Application Metrics | Counters, gauges, histograms (e.g., request latency, error rates). |
+| Alerting & Dashboards | Prometheus rules, Datadog monitors, Grafana dashboard JSON. |
+
+## Procedure
+
+### Step 1 — Extract Standards
+Extract from `observability.md`:
+- The approved logging library.
+- Required log levels (e.g., `DEBUG` in dev, `INFO` in prod).
+- Required structured fields (e.g., `requestId`, `tenantId`).
+
+### Step 2 — Enforce Compliance and PII Masking
+Extract from `compliance.md`:
+- Identify fields that MUST NEVER be logged (e.g., passwords, credit card numbers, raw request bodies).
+- Implement redaction/masking at the logger configuration level if possible.
+
+### Step 3 — Instrument Tracing Context
+When instrumenting a request flow:
+- Ensure trace IDs (like `x-b3-traceid` or OpenTelemetry headers) are parsed at the entry point.
+- Ensure the trace ID is attached to ALL subsequent log emissions and downstream HTTP calls.
+
+### Step 4 — Define Actionable Metrics
+Instead of generic logs, emit actionable metrics for:
+- Throughput (requests per second).
+- Error rates (4xx vs 5xx).
+- Latency/Duration (histograms of processing time).
+
+### Step 5 — Standardize Error Handling
+When logging exceptions:
+- Always log the full stack trace for unhandled errors.
+- Do not swallow errors (e.g., `catch (e) { log(e.message) }` loses the stack trace).
+- Ensure the log distinguishes between client errors (validation) and server errors (crashes).
+
+## Quality Check
+
+Use this checklist when reviewing observability code:
+
+- Are logs structured (JSON) rather than plain text strings?
+- Is context (like Request ID) present in every log entry for a transaction?
+- Are sensitive fields (tokens, passwords, PII) explicitly redacted?
+- Are metrics using standardized naming conventions (e.g., snake_case for Prometheus)?
+- Are errors logged with stack traces and sufficient context to debug without guessing?
+
+## Anti-Pattern
+
+- `console.log()` or equivalent generic print statements in production code.
+- Logging the entire raw HTTP Request or Response object.
+- Silently swallowing exceptions without logging them.
+- Emitting high-cardinality data (like User IDs) as metric labels/tags instead of log fields.
+
+## Output Contract
+
+When using this skill, the output should include:
+
+1. the project docs consulted
+2. the instrumentation code (logging, tracing, or metrics)
+3. the structured payload shape being emitted
+4. the PII masking and security constraints verified
+5. how the new telemetry can be validated (e.g., local mock server, stdout check)
+
+## Neutral Prompt Shape
+`@agent use observability on [Target Service/Component] focusing on [Specific Metrics/Logs].`
+
+## Example Prompt
+- "Instrument this service with structured logging and trace context."
+- "Review this controller to ensure PII is masked before logging."
+- "Design Prometheus metrics for this asynchronous background job."

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

@@ -1,34 +1,30 @@
 ---
-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 |
 | --- | --- |
-| `docs/eyehateagent-contract.md` | Ownership map and canonical doc contract |
+| 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,13 +45,11 @@ 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
 
-Use the project docs defined by `docs/eyehateagent-contract.md` as the default source of truth for documentation ownership unless the repository explicitly states otherwise.
+Use the active EHA rules as the default source of truth for documentation ownership unless the repository explicitly states otherwise.
 
 ### Step 2 — Compare dependent layers
 
@@ -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."