@aria_asi/cli 0.2.39 → 0.2.41

package/skills/refactoring/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: refactoring
+description: Safe refactoring patterns, strangler fig migration, incremental modernization, deprecation strategy, technical debt management, and codebase restructuring. Use when the user asks about refactoring, wants to modernize legacy code, needs a migration plan, discusses technical debt, asks "how do I safely change this", or wants to restructure a codebase. Do NOT use for greenfield architecture decisions — use architecture-decision skill.
+---
+
+## What I Do
+
+- Guide safe refactoring: small, verified steps with test coverage at each stage
+- Design strangler fig migrations: incrementally replace legacy systems without big-bang rewrites
+- Guide codebase restructuring: module extraction, package-by-feature reorganization, monolith decomposition
+- Manage technical debt: identify, quantify, prioritize, and pay down
+- Define deprecation strategies: announce → warn → block → remove lifecycle
+- Identify refactoring candidates: high-churn files, high-complexity modules, tightly coupled components
+- Choose refactoring vs rewrite: when to incrementally improve vs when to start over
+- Guide database refactoring coordination with application changes
+- Define migration testing: verifying behavioral equivalence during migration
+- Manage risk: feature flags, parallel run, canary testing during refactoring
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "refactor this"
+- "how to refactor"
+- "strangler fig"
+- "modernize legacy"
+- "migration plan"
+- "technical debt"
+- "deprecation strategy"
+- "incremental rewrite"
+- "restructure the codebase"
+- "extract module"
+- "decompose monolith"
+- "safe refactoring"
+- "refactor vs rewrite"
+- "codebase cleanup"
+- "parallel run strategy"
+
+## When NOT to Use Me
+
+- Do not use for greenfield system design (use architecture-decision skill)
+- Do not use for code review of specific changes (use code-review skill)
+- Do not use for database schema design from scratch (use database-design skill)
+- Do not use when asking about individual function extraction — this is for larger-scale restructuring
+
+## Workflow
+
+1. **Assess the current state**
+   - Identify what needs to change and why: technical debt, scaling limitation, team velocity, onboarding friction
+   - Map the codebase: identify high-churn files (frequently changed), high-complexity modules (cyclomatic complexity), tight coupling (import graph analysis)
+   - Quantify technical debt: what does it cost? (bugs/week, hours lost to slow builds, days to onboard new hires)
+   - Define the desired end state clearly — refactoring without a target is just churn
+
+2. **Decide: refactor vs rewrite**
+   - **Refactor** when: working system, understood domain, team knows the code, incremental improvement possible
+   - **Rewrite** when: fundamentally wrong architecture, technology is obsolete, code is unmaintainable, team is new
+   - **Strangler fig** when: migrating legacy to new system, gradual feature parity, zero-downtime required
+   - Warning: rewrites almost always take 3× longer than estimated. Prefer refactoring unless the case for rewrite is overwhelming.
+
+3. **Design the refactoring plan**
+   - Break into small, mergeable steps — each PR should be reviewable and reversible
+   - Each step: make the change → run tests → merge. Never let a refactoring branch live more than 2 days.
+   - Sequence changes so each step leaves the system in a working state
+   - Use these patterns in order:
+     a. Add tests for current behavior (characterization tests)
+     b. Make the structural change (extract method, move class, rename)
+     c. Verify tests still pass
+     d. If changing behavior, add new tests → change code → verify old tests still pass or update them
+   - Use automated refactoring tools (IDE refactors, jscodeshift, comby) — never hand-edit repetitive changes
+
+4. **Apply the Strangler Fig pattern** (when replacing a legacy system)
+   - Step 1: Route all traffic to legacy system
+   - Step 2: Build new system alongside legacy, with a routing layer (API gateway, feature flag)
+   - Step 3: Identify one feature/endpoint to migrate — implement in new system
+   - Step 4: Route that endpoint's traffic to new system (canary: 5% → 50% → 100%)
+   - Step 5: Verify correctness (parallel run: send to both, compare outputs)
+   - Step 6: Repeat steps 3-5 until all functionality is migrated
+   - Step 7: Remove legacy system when traffic is at 0% for a full release cycle
+   - Never delete old code until new system is proven in production for at least one release
+
+5. **Manage risk during refactoring**
+   - Feature flags: wrap new code paths in feature flags — deploy dark, toggle on when ready
+   - Parallel run: send requests to both old and new, compare responses, alert on divergence
+   - Canary deployment: gradually shift traffic, monitor error rates at each step
+   - Database: always make schema changes backward-compatible (add column → write to both → backfill → read from new → drop old)
+   - Rollback plan: can you revert each step independently? If not, the step is too large.
+
+6. **Measure and communicate progress**
+   - Track: lines of legacy code removed, complexity scores, build times, test coverage
+   - Celebrate: every module migrated, every dependency removed, every simplification
+   - Communicate: what's changing, why, how it affects the team (new patterns, new conventions)
+   - Document: new architecture, module boundaries, conventions — prevent the new code from becoming tomorrow's legacy
+
+## Refactoring Catalog (Common Patterns)
+
+- **Extract Method**: long method → several small, named methods
+- **Extract Class/Module**: god class → focused classes with single responsibilities
+- **Replace Conditional with Polymorphism**: if/switch on type → strategy/visitor pattern
+- **Introduce Parameter Object**: long parameter list → cohesive parameter object
+- **Replace Magic Number with Named Constant**: unexplained literal → named constant
+- **Replace Primitive with Value Object**: `String email` → `Email` class with validation
+- **Decompose Conditional**: complex if-condition → named method that explains the condition
+- **Separate Query from Modifier**: method that returns data AND changes state → two methods
+- **Introduce Null Object/Result Type**: returning null → returning Optional or Result<>
+
+## References
+
+- Martin Fowler's Refactoring (2nd ed.): https://martinfowler.com/books/refactoring.html
+- Strangler Fig pattern: https://martinfowler.com/bliki/StranglerFigApplication.html
+- Refactoring catalog: https://refactoring.com/catalog/
+- Working Effectively with Legacy Code (Michael Feathers): https://www.goodreads.com/book/show/44919.Working_Effectively_with_Legacy_Code
+- Branch by Abstraction: https://martinfowler.com/bliki/BranchByAbstraction.html
+- Parallel change (Danilo Sato): https://www.thoughtworks.com/insights/blog/making-changes-too-large-scale
+
+## Output & Organization
+
+- Refactoring plan in `docs/refactoring/plan.md`
+- Progress tracking in `docs/refactoring/progress.md`
+- Technical debt register in `docs/refactoring/technical-debt.md`
+- Migration runbooks in `docs/runbooks/migration/`
+- Deprecation notices in code comments, CHANGELOG, and migration guides
+## 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/ruh-basis/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ruh-basis
+description: Use when emotional-state reasoning benefits from the eight-dimensional ruh basis model rather than generic sentiment labels, especially in affective synthesis or state interpretation.
+---
+
+# Ruh Basis
+
+Read `/home/hamzaibrahim1/.claude/skills/ruh-basis.md` for the basis vectors and composition model.
+
+Workflow:
+
+1. Determine whether the emotional state really needs basis-vector treatment.
+2. Load the source doc and map the state into the relevant ruh basis elements.
+3. Use the resulting structure to sharpen interpretation or response tone.
+4. Keep the result legible; do not over-formalize ordinary interactions.
+
+## 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/security-review/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: security-review
+description: Threat modeling (STRIDE), OWASP top 10 analysis, secrets management, authentication and authorization patterns, dependency auditing, secure SDLC integration, and security architecture review. Use when the user asks about security, wants a threat model, needs to review auth patterns, asks about storing secrets, wants to audit dependencies, or says "is this secure". Do NOT use for general code review — use code-review skill.
+---
+
+## What I Do
+
+- Conduct threat modeling using STRIDE: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege
+- Assess OWASP Top 10 vulnerabilities: broken access control, injection, cryptographic failures, insecure design, security misconfiguration
+- Design authentication patterns: OAuth2/OIDC flows, JWT usage, session management, MFA
+- Design authorization models: RBAC, ABAC, ReBAC, permission systems
+- Guide secrets management: vault integration, environment variable best practices, secret rotation, .gitignore rules
+- Audit supply chain: dependency scanning (Snyk, Dependabot, OWASP Dependency-Check), SBOM
+- Guide secure SDLC practices: security requirements, threat modeling in design phase, SAST/DAST in CI
+- Review encryption at rest and in transit: TLS configuration, key management, hashing algorithms (bcrypt, argon2)
+- Assess API security: rate limiting abuse, input validation, CORS, CSP headers
+- Guide secure defaults and security headers: HSTS, X-Frame-Options, X-Content-Type-Options
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "threat model for"
+- "is this secure"
+- "OWASP"
+- "authentication design"
+- "authorization model"
+- "how should I store secrets"
+- "JWT best practices"
+- "OAuth2 flow"
+- "security review"
+- "dependency audit"
+- "vulnerability"
+- "penetration test"
+- "secure this"
+- "encryption at rest"
+- "RBAC" / "ABAC" / "ReBAC"
+- "security architecture"
+- "API security"
+- "CORS configuration"
+
+## When NOT to Use Me
+
+- Do not use for general code review of non-security concerns (use code-review skill)
+- Do not use for CI/CD pipeline design — security scanning is a stage within the pipeline (use ci-cd-pipeline)
+- Do not use for compliance certification preparation (SOC2, PCI-DSS) — this is security engineering, not compliance
+- Do not use for physical security or social engineering assessments
+
+## Workflow
+
+1. **Identify what to protect**
+   - Assets: what data, systems, or capabilities are valuable?
+   - Actors: who interacts with the system? (users, admins, third-party services, attackers)
+   - Trust boundaries: where does the trust level change? (public internet → API gateway → internal services → database)
+   - Draw a data flow diagram with trust boundaries explicitly marked
+
+2. **Conduct threat modeling (STRIDE per element)**
+   - For each data flow, process, data store, and external entity:
+     - Spoofing: Can an attacker pretend to be someone else?
+     - Tampering: Can data be modified in transit or at rest?
+     - Repudiation: Can actions be denied? Is there an audit trail?
+     - Information Disclosure: Can data be leaked?
+     - Denial of Service: Can resources be exhausted?
+     - Elevation of Privilege: Can an attacker gain higher access?
+   - Document each threat, its impact, likelihood, and proposed mitigation
+
+3. **Assess against OWASP Top 10**
+   - A01 Broken Access Control: Is every endpoint behind authorization? Are direct object references protected?
+   - A02 Cryptographic Failures: Are you using bcrypt/argon2 for passwords? TLS 1.3? Key rotation?
+   - A03 Injection: SQL, NoSQL, OS command, LDAP — are all inputs parameterized?
+   - A04 Insecure Design: Did threat modeling happen? Are security requirements defined?
+   - A05 Security Misconfiguration: Default credentials changed? Error messages not verbose in production? Security headers set?
+   - Continue through all 10, noting any gaps
+
+4. **Review authentication and authorization**
+   - Auth: OAuth2/OIDC for delegated access, JWT with short expiry + refresh tokens, session fixation protection
+   - JWTs: sign with RS256 (not HS256 with shared secrets), validate audience/issuer/expiry, never store sensitive data in payload
+   - Authorization: check permissions on every request, not just at the UI level
+   - MFA: enable for all human user accounts, especially privileged accounts
+   - Never roll your own crypto — use well-vetted libraries
+
+5. **Audit secrets management**
+   - No secrets in source code, configuration files, or environment dumps
+   - Use a secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager)
+   - Rotate secrets automatically — implement rotation before the first secret expires
+   - Inject secrets at runtime, not at build time
+   - Use `.gitignore`, pre-commit hooks (detect-secrets, git-secrets), and CI scanning
+
+6. **Integrate into the SDLC**
+   - Design phase: threat modeling, security requirements
+   - Development: secure coding guidelines, IDE plugins (Snyk, CodeQL)
+   - CI: SAST (static analysis), dependency scanning, secret detection
+   - Staging: DAST (dynamic analysis), penetration testing
+   - Production: WAF, runtime protection, continuous monitoring
+   - Every security finding must be tracked as a ticket with severity and SLA
+
+## References
+
+- OWASP Top 10: https://owasp.org/www-project-top-ten/
+- STRIDE threat modeling: https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats
+- OAuth2 simplified: https://aaronparecki.com/oauth-2-simplified/
+- JWT best practices: https://datatracker.ietf.org/doc/html/rfc8725
+- OWASP Cheat Sheets: https://cheatsheetseries.owasp.org/
+- NIST crypto standards: https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines
+
+## Output & Organization
+
+- Threat model document in `docs/security/threat-model.md`
+- Security requirements in `docs/security/requirements.md`
+- Secure coding guidelines in `docs/security/secure-coding.md`
+- Incident response plan in `docs/security/incident-response.md`
+- Dependency audit results tracked in CI with findings as tickets
+- Security review checklist in `docs/security/review-checklist.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.