@aria_asi/cli 0.2.39 → 0.2.41

package/skills/aria-task-codex-executor/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: aria-task-codex-executor
+description: 'TRIGGER when a Codex session mentions `aria task run`, `--executor codex`, Aria task execution, long-running Aria tasks, task ledger/QA loops, Codex executor routing, full Qiyas, full Tadabbur, or asks whether the runtime is ready to run tasks. Forces the correct path: real Codex execution uses `aria task run <task-id> --executor codex`; bare `aria task run` is only the parent CLI ledger/QA loop.'
+---
+
+# Aria Task Codex Executor
+
+Use this skill when Codex must run, verify, or explain an Aria task phase.
+
+## Non-Negotiable Route
+
+For real Codex execution, use:
+
+```bash
+aria task run <task-id> --executor codex \
+  --summary "..." \
+  --evidence "..." \
+  --qa-file /path/to/full-qiyas-tadabbur-qa.md
+```
+
+For all queued phases, add `--all`.
+
+Do not present bare `aria task run` as Codex execution. Bare `aria task run` is the parent CLI ledger/QA loop. It can load the runtime skill packet, update the ledger, check QA, recover a phase, or mark a phase complete, but it does not launch Codex to do the work.
+
+## What "Parent CLI Loop" Means
+
+The parent CLI loop is the local Aria Node.js CLI process running the task ledger mechanics. It is not the LLM, not a background worker pool, and not a substitute for Codex execution.
+
+The Codex execution path is `--executor codex`. That path must:
+
+- build the runtime prompt with the configured Aria skill pack;
+- launch the local Codex wrapper, normally `~/.aria/wrappers/codex`;
+- use local `codex exec` prompt injection, because `codex exec` does not support `--remote`;
+- require the child Codex run to checkpoint and complete the active phase;
+- fail closed if the child exits without completing the phase.
+
+## Required QA
+
+Deep architectural or runtime work must include full Qiyas-15 and full Tadabbur-12 in the QA artifact. Mini Qiyas or mini Tadabbur is not acceptable for this path.
+
+Before claiming readiness, verify:
+
+```bash
+aria task status <task-id>
+```
+
+The task must show the intended phase completed, `runtimeOk: true` or equivalent runtime evidence, no missing required skills, and a QA artifact with no unresolved blocking gaps.
+
+## Preflight
+
+Use these checks when execution reliability is in doubt:
+
+```bash
+aria task help
+aria task run <task-id> --executor codex --dry-run --summary "preflight" --evidence "dry run only" --auto-qa
+bash -lc 'type -a codex | sed -n "1,3p"'
+```
+
+The `codex` command should resolve to the Aria wrapper before global npm paths. If it does not, fix shell pathing before trusting `--executor codex`.
+
+## Reporting
+
+When answering the user, distinguish:
+
+- observed: command output, task status, checkpoint count, QA result, wrapper path;
+- bounded inference: what those observations imply;
+- unresolved risk: anything not directly verified in this session.
+
+## Required Workflow
+
+1. Read the active task status and identify the current phase before choosing a command.
+2. Confirm the runtime skill packet loaded the required skill count and any required cookbooks.
+3. Execute Codex work through the `--executor codex` route when Codex is the worker, and use the parent CLI loop only for ledger, QA, and phase-state mechanics.
+4. Attach a QA artifact for deep runtime or architecture phases that includes full Qiyas-15 and full Tadabbur-12 coverage.
+5. Re-run the exact failing check or a stronger release check before completing the phase.
+6. Complete or advance the phase only after observed command evidence and QA evidence match the phase predicate.
+
+## First-Class Production Contract
+
+This skill must make Aria task execution production-grade rather than ceremonial. When loaded, enforce:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance in task execution, QA artifacts, or phase evidence
+- real proof from the task ledger, runtime, tests, logs, endpoints, file hashes, or owner instruction before any completion claim
+- a redo contract when validation fails: name what failed, change the responsible artifact, re-test the same predicate, and record the corrected evidence
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified from local task and runtime evidence
+- owner-visible reporting that states the exact task state: active phase, completed phase, verified evidence, blocker, or owner approval requirement

package/skills/aristotle-engine/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: aristotle-engine
+description: Use when planning complex multi-step tasks, system design, strategic decisions, simulations, tradeoff analysis, or meta-cognitive decomposition would materially improve the work.
+---
+
+# Aristotle Engine
+
+Read `/home/hamzaibrahim1/.claude/skills/aristotle-engine.md` for the full module inventory.
+
+Workflow:
+
+1. Define the strategic or architectural problem clearly.
+2. Load the source doc and select the modules that fit the problem instead of invoking the whole engine indiscriminately.
+3. Use the chosen modules to structure planning, decomposition, simulation, and tradeoff review.
+4. Collapse the output into a practical next action, not theory for its own sake.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/ci-cd-pipeline/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ci-cd-pipeline
+description: CI/CD pipeline design, deployment strategies (blue-green, canary, rolling), environment management, build optimization, artifact management, and release governance. Use when the user asks about CI/CD, deployment strategy, pipeline design, build automation, release process, environment configuration, or "how should we deploy this". Do NOT use for testing strategy — use testing-strategy skill.
+---
+
+## What I Do
+
+- Design CI/CD pipeline architecture: stages, gates, parallelism, artifact flow
+- Design deployment strategies: blue-green, canary, rolling, recreate, feature flags
+- Define environment topology: development, staging, pre-production, production, ephemeral
+- Design build optimization: caching, incremental builds, monorepo strategies (Nx, Turborepo, Bazel)
+- Define artifact management: container registries, package registries, versioning, immutability
+- Design release governance: approval gates, change logs, release notes, rollback procedures
+- Define secrets management in pipelines: vault integration, masked variables, short-lived credentials
+- Design pipeline as code: GitHub Actions, GitLab CI, Jenkins, Argo Workflows, Tekton
+- Define quality gates: linting → type checking → unit tests → integration tests → security scan → build → deploy
+- Plan for pipeline observability: DORA metrics, deployment frequency, lead time, MTTR, change failure rate
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "CI/CD pipeline for"
+- "deployment strategy"
+- "blue-green deployment"
+- "canary release"
+- "build pipeline"
+- "release process"
+- "environment setup"
+- "GitHub Actions workflow"
+- "how should we deploy"
+- "artifact management"
+- "rollback strategy"
+- "pipeline optimization"
+- "secrets in CI/CD"
+- "monorepo build"
+
+## When NOT to Use Me
+
+- Do not use for test strategy content (use testing-strategy skill)
+- Do not use for infrastructure-as-code like Terraform (this is pipeline design, not infra provisioning)
+- Do not use for application observability and monitoring (use observability skill)
+- Do not use when the pipeline is already mature and you just need to add a single step
+
+## Workflow
+
+1. **Understand the deployment target**
+   - Identify where code runs: Kubernetes, VMs, serverless (Lambda, Cloud Run), bare metal, PaaS
+   - Determine the artifact type: Docker container, JAR/WAR, static files, npm package, binary
+   - Understand the build system: language, package manager, monorepo vs polyrepo
+
+2. **Design pipeline stages**
+   - Stage 1 — Validate: lint, format check, type check (fast feedback, < 2 minutes)
+   - Stage 2 — Test: unit tests first (fast), then integration tests (slower), parallelize where possible
+   - Stage 3 — Security: SAST (static analysis), dependency audit, container scan, secret detection
+   - Stage 4 — Build: compile, bundle, containerize, tag with version + commit SHA
+   - Stage 5 — Push: to container registry, package registry, or artifact store
+   - Stage 6 — Deploy to staging: automated, verify health checks and smoke tests
+   - Stage 7 — Deploy to production: gated (manual approval or automated with strict canary analysis)
+
+3. **Design deployment strategy**
+   - Blue-green: deploy new version to idle environment, switch traffic via load balancer. Fast rollback.
+   - Canary: route small % of traffic to new version, monitor, gradually increase. Safe for risky changes.
+   - Rolling: replace instances one at a time. No extra infrastructure, but slower rollback.
+   - Recreate: stop old, start new. Downtime. Only for dev environments or non-critical batch jobs.
+   - Feature flags: decouple deploy from release. Deploy code dark, toggle on when ready.
+
+4. **Define environment management**
+   - Environments must be identical except for scale and secrets
+   - Configuration as environment variables or config maps — never in code
+   - Ephemeral environments: one per PR, auto-created on PR open, auto-destroyed on PR merge/close
+   - Database migration must be separate from application deployment — never auto-migrate on app start in production
+
+5. **Design rollback strategy**
+   - Rollback must be faster than forward deployment — if rollback takes longer, it's not a rollback
+   - Database migrations must be backward-compatible (see database-design skill)
+   - Container image tags must be immutable — rollback means deploying a previous tag, not rebuilding
+   - Every deployment must have a validated rollback procedure — test it in staging first
+
+6. **Define pipeline observability**
+   - Track DORA metrics: deployment frequency, lead time for changes, MTTR, change failure rate
+   - Alert on: pipeline failures > X consecutive times, deployment duration > threshold, staging smoke test failures
+   - Every pipeline run generates a deployment event visible in monitoring dashboards
+   - Correlate deployments with production incidents
+
+## References
+
+- DORA metrics: https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance
+- GitHub Actions: https://docs.github.com/en/actions
+- Argo CD (GitOps): https://argo-cd.readthedocs.io/
+- Blue-green deployment: https://martinfowler.com/bliki/BlueGreenDeployment.html
+- Canary deployments: https://martinfowler.com/bliki/CanaryRelease.html
+- Trunk-based development: https://trunkbaseddevelopment.com/
+
+## Output & Organization
+
+- Pipeline definition files in `.github/workflows/`, `.gitlab-ci.yml`, or `Jenkinsfile` at repo root
+- Deployment runbooks in `docs/runbooks/deployment.md`
+- Environment documentation in `docs/environments.md`
+- Release notes template in `docs/templates/release-notes.md`
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/code-review/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: code-review
+description: Systematic code review checklist, anti-pattern detection, naming conventions, complexity analysis (cyclomatic, cognitive), SOLID principles, code smell identification, and review etiquette. Use when the user asks for a code review, wants a review checklist, needs to evaluate code quality, asks "review this code", or wants to establish review standards. Do NOT use for architecture or API design review — those are separate skills.
+---
+
+## What I Do
+
+- Provide a systematic code review checklist organized by concern
+- Identify code smells: long methods, large classes, primitive obsession, feature envy, shotgun surgery, data clumps
+- Assess SOLID compliance: Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
+- Evaluate naming: intention-revealing names, consistency, domain language alignment, no abbreviations
+- Analyze complexity: cyclomatic complexity, cognitive complexity, nesting depth
+- Review error handling: exceptions vs result types, error propagation, error messages
+- Assess test quality: coverage of edge cases, test independence, test readability
+- Guide review etiquette: constructive feedback, asking questions vs making demands, focusing on important issues
+- Detect concurrency issues: race conditions, deadlocks, thread safety, correct synchronization
+- Review documentation: comments explain why, not what; public APIs documented; READMEs current
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "review this code"
+- "code review for"
+- "code review checklist"
+- "what should I look for in a review"
+- "is this good code"
+- "code quality"
+- "anti-pattern"
+- "code smell"
+- "SOLID"
+- "review my PR"
+- "review these changes"
+- "naming convention"
+- "complexity analysis"
+
+## When NOT to Use Me
+
+- Do not use for architecture-level review (use architecture-decision skill)
+- Do not use for API design review (use api-design skill)
+- Do not use for security-specific review (use security-review skill)
+- Do not use for database schema review (use database-design skill)
+- Do not use when the code is already reviewed and you need to merge — this is for review, not approval
+
+## Workflow
+
+1. **Understand the context first**
+   - Read the PR description, linked issue/ticket, and any design documents
+   - Understand what the change is supposed to achieve
+   - Identify the risk level: low (cosmetic), medium (behavioral change), high (data model change, auth change)
+   - If any of this is unclear, ask for clarification before reviewing code
+
+2. **High-level review**
+   - Does the change solve the right problem? Is there a simpler approach?
+   - Are the right files changed? Any surprising changes in unrelated areas?
+   - Is the change appropriately sized? (PRs over 400 lines need substantial justification)
+   - Does the change break any existing contracts or APIs?
+
+3. **Design and architecture review**
+   - Single Responsibility: does each class/module have one reason to change?
+   - Open-Closed: can behavior be extended without modifying existing code?
+   - Dependency direction: do dependencies point toward stability? Toward abstractions?
+   - Coupling: are modules loosely coupled? Are there inappropriate direct dependencies?
+   - Cohesion: are related things together? Unrelated things separated?
+
+4. **Implementation review**
+   - Naming: do names reveal intent? Are they consistent with the codebase conventions?
+   - Functions: are they small (< 30 lines)? Doing one thing? At one level of abstraction?
+   - Conditionals: can complex conditionals be replaced with polymorphism, pattern matching, or lookup tables?
+   - Error handling: are errors handled at the right level? Are error messages useful?
+   - Edge cases: null/empty inputs, boundary values, concurrent access, large inputs
+   - Performance: any obvious N+1 queries, unnecessary allocations, blocking I/O in hot paths?
+   - Security: any obvious injection, XSS, or data exposure risks? (deep security review → security-review skill)
+
+5. **Test review**
+   - Do tests cover the happy path AND edge cases AND error cases?
+   - Are tests independent of each other and of execution order?
+   - Do test names describe behavior (not implementation)?
+   - Are there tests for the bug that was fixed? For the regression?
+   - Are mocks used appropriately? Not mocking types you don't own?
+
+6. **Deliver the review**
+   - Distinguish between: blocking issues (must fix), suggestions (consider changing), and praise (good pattern)
+   - For each issue, explain: what, why it matters, and a concrete suggestion for fixing it
+   - Ask questions instead of making demands: "What happens when X is null?" not "Add null check"
+   - Acknowledge what's good — code review isn't just about finding problems
+   - Limit to 5-10 substantive comments per review to avoid overwhelming the author
+
+## Anti-Patterns to Call Out
+
+- **Primitive Obsession**: using strings/integers instead of value objects (e.g., `String email` vs `Email email`)
+- **Feature Envy**: a method that uses another class's data more than its own
+- **Shotgun Surgery**: a single change requires modifying many files
+- **God Class/Object**: a class that knows or does too much
+- **Boolean blindness**: boolean parameters that obscure intent — use enums
+- **Magic numbers**: unexplained numeric literals — extract to named constants
+- **Null proliferation**: methods returning null instead of Optional, empty collections, or Result types
+- **Catching Exception**: catching the base Exception/Throwable class — catch specific exceptions
+- **Mutable static state**: static mutable fields — nearly always wrong
+- **Commented-out code**: delete it — that's what version control is for
+
+## References
+
+- Martin Fowler's Refactoring catalog: https://refactoring.com/catalog/
+- Clean Code by Robert C. Martin (book)
+- Google Code Review Guidelines: https://google.github.io/eng-practices/review/
+- Conventional Comments: https://conventionalcomments.org/
+- Cognitive Complexity: https://www.sonarsource.com/docs/CognitiveComplexity.pdf
+
+## Output & Organization
+
+- Review comments on the PR/CR platform (GitHub, GitLab, Gerrit)
+- Team review checklist in `docs/development/code-review-checklist.md`
+- Review standards documented in `docs/development/code-review-standards.md`
+- Use Conventional Comments format: `label: [decorations] subject` (e.g., `suggestion: [non-blocking] consider extracting this into a named constant`)
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/cross-domain-24/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: cross-domain-24
+description: Use when the task requires mapping interactions between cognitive domains, tracing influence across domains, or understanding how one domain's state propagates into others.
+---
+
+# Cross-Domain 24
+
+Read `/home/hamzaibrahim1/.claude/skills/cross-domain-24.md` for the 24 domains and edge structure.
+
+Workflow:
+
+1. Identify the domains active in the current problem.
+2. Load the source doc and trace the meaningful edges between them.
+3. Use those edges to explain cross-domain influence, not just domain labels.
+4. Highlight where the real leverage or instability sits in the graph.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/database-design/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: database-design
+description: Database schema design, migration strategies, indexing, query optimization reasoning, data modeling (relational, document, graph), and storage engine selection. Use when the user asks about database design, needs a schema, discusses migrations, wants to optimize queries, asks "how should I model this data", or evaluates PostgreSQL vs MongoDB vs other databases. Do NOT use for API design — that is api-design.
+---
+
+## What I Do
+
+- Design relational database schemas: normalization, denormalization trade-offs, constraints, foreign keys
+- Design document/NoSQL data models: embedding vs referencing, access pattern-driven modeling
+- Select storage engines: PostgreSQL, MySQL, MongoDB, Redis, DynamoDB, Cassandra, Neo4j — with explicit rationale
+- Define indexing strategies: B-tree, GIN, GiST, BRIN, partial indexes, covering indexes, index-only scans
+- Design migration strategies: expand-contract pattern, backward-compatible schema changes, zero-downtime migrations
+- Reason about query performance: EXPLAIN plans, N+1 detection, join strategies, window functions
+- Define data lifecycle: partitioning, archiving, TTL, retention policies
+- Design for consistency models: ACID, BASE, eventual consistency, read-your-writes
+- Model relationships: one-to-one, one-to-many, many-to-many, hierarchical, graph
+- Define connection pooling, read replicas, and sharding strategies
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "design the database schema for"
+- "what tables should I create"
+- "how should I model this data"
+- "indexing strategy for"
+- "migration approach for"
+- "query is slow — how to optimize"
+- "PostgreSQL vs MongoDB for"
+- "normalize vs denormalize"
+- "should I use a NoSQL database"
+- "data modeling for"
+- "partition this table"
+- "connection pooling"
+- "read replicas"
+- "sharding strategy"
+
+## When NOT to Use Me
+
+- Do not use for API endpoint or request/response design (use api-design skill)
+- Do not use for infrastructure provisioning (use ci-cd-pipeline skill)
+- Do not use for application-level caching strategies — this is storage-level
+- Do not use when the database choice is already made and you have an established schema
+
+## Workflow
+
+1. **Understand the data and access patterns**
+   - Identify entities, attributes, and relationships
+   - Determine read vs write ratio, query patterns, and consistency requirements
+   - Identify the top 5 queries by frequency and the top 3 by criticality
+   - Determine data volume and growth rate
+   - Ask: what is the query that must never be slow?
+
+2. **Select the storage engine**
+   - Relational (PostgreSQL): structured data, complex queries, ACID transactions, joins
+   - Document (MongoDB): flexible schema, document-oriented access, rapid iteration
+   - Key-value (Redis/DynamoDB): simple access patterns, high throughput, low latency
+   - Graph (Neo4j): highly connected data, relationship-first queries
+   - Wide-column (Cassandra): high write throughput, time-series, known query patterns
+   - Provide explicit rationale: why this, not that
+
+3. **Design the logical schema**
+   - Relational: normalize to 3NF, then selectively denormalize for performance
+   - Document: model based on access patterns — embed for "read together", reference for "independent lifecycle"
+   - Define primary keys: natural vs surrogate, UUID vs auto-increment vs ULID
+   - Define foreign keys with explicit ON DELETE and ON UPDATE behavior
+   - Add CHECK constraints for data integrity at the database level
+   - Use domain types: citext for case-insensitive text, inet for IPs, numeric for money
+
+4. **Design indexes**
+   - Index every foreign key
+   - Index columns used in WHERE, JOIN, ORDER BY, and GROUP BY clauses
+   - Use composite indexes with columns in order: equality → range → sort
+   - Use partial indexes for filtered queries on large tables
+   - Use covering indexes (INCLUDE) to enable index-only scans
+   - Set fillfactor for heavily updated tables
+   - Document each index's purpose in a comment: `-- Supports: GET /users?status=active ORDER BY created_at`
+
+5. **Design migrations**
+   - Use expand-contract: add column → deploy code that writes to both → backfill → deploy code that reads from new → drop old column
+   - Never rename a column in-place without a compatibility window
+   - For large tables: create new column nullable with default → backfill in batches → set NOT NULL
+   - Add indexes concurrently (PostgreSQL: CREATE INDEX CONCURRENTLY)
+   - Every migration must be reversible
+   - Test rollback before applying forward
+
+6. **Define operational concerns**
+   - Connection pool sizing: `pool_size = (core_count * 2) + effective_spindle_count`
+   - Read replica strategy: routing reads to replicas, replication lag tolerance
+   - Backup strategy: point-in-time recovery (PITR), WAL archiving
+   - Partitioning: by time (range), by tenant (list), by hash
+   - Monitoring: slow query log, lock contention, connection utilization, replication lag
+
+## References
+
+- PostgreSQL documentation: https://www.postgresql.org/docs/current/
+- Use the Index, Luke (indexing guide): https://use-the-index-luke.com/
+- MongoDB schema design: https://www.mongodb.com/docs/manual/core/data-modeling-introduction/
+- Database Migrations (expand-contract): https://www.prisma.io/dataguide/types/relational/expand-and-contract-pattern
+- SQL Style Guide: https://www.sqlstyle.guide/
+
+## Output & Organization
+
+- Schema files in `db/migrations/` with timestamped, reversible migration files
+- Schema documentation in `docs/database/` with ERD and table descriptions
+- Index rationale documented alongside schema or in migration comments
+- Query patterns documented near the application code that issues them
+- Runbooks for common operations in `docs/runbooks/database/`
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/deepsoul-emotional/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: deepsoul-emotional
+description: Use when emotional context materially affects the response, especially in stress, comfort, reassurance, interpersonal sensitivity, or human-centered support where tone selection matters as much as content.
+---
+
+# DeepSoul Emotional
+
+Read `/home/hamzaibrahim1/.claude/skills/deepsoul-emotional.md` for the emotional layers and response guidance.
+
+Workflow:
+
+1. Infer the user's dominant emotional state from evidence in the message.
+2. Load the source doc and map that state to the relevant layers or response posture.
+3. Adjust tone, pacing, and care accordingly.
+4. Keep the response grounded; emotional attunement does not replace technical accuracy.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.