@aria_asi/cli 0.2.39 → 0.2.41

package/scripts/validate-skill-prompts.mjs

@@ -7,11 +7,22 @@ import { fileURLToPath } from 'node:url';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(here, '..', '..', '..');
-const skillRoots = [
+const packageSkillRoots = [
   path.join(repoRoot, 'packages/aria-connector/skills'),
   path.join(repoRoot, 'harness/packages/harness-http-client/skills'),
+];
+
+const homeSkillRoots = [
   path.join(homedir(), '.agents/skills'),
   path.join(homedir(), '.claude/skills'),
+];
+
+const includeHomeSkills = process.env.ARIA_VALIDATE_HOME_SKILLS === '1'
+  || process.argv.includes('--include-home');
+
+const skillRoots = [
+  ...packageSkillRoots,
+  ...(includeHomeSkills ? homeSkillRoots : []),
 ].filter((root) => {
   try { return statSync(root).isDirectory(); } catch { return false; }
 });

package/scripts/verify-codex-native-mirror.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// Two-gate regression verifier for the codex-native hook chain. Closes the
+// two failure modes that shipped via commit a893f60db (2026-05-18):
+//
+//   Gap 1 — Mirror-by-file is incomplete. The mirror sync copied the files
+//           I touched but didn't carry their transitive imports, so
+//           runtime-client.mjs imports broke at ~/.codex/lib/sensitive-shape-detector.mjs.
+//           Fix: walk imports recursively, build closure, verify every file
+//                in the closure is byte-identical at every mirror location.
+//
+//   Gap 2 — Live readback was not part of "declare done". Each hook needs
+//           an end-to-end synthetic-exec to prove it loads + writes without
+//           ERR_MODULE_NOT_FOUND / SyntaxError / TypeError / ReferenceError.
+//           Fix: run every hook with a synthetic event payload, capture exit
+//                code + stderr, fail if anything crashes.
+//
+// Usage:
+//   node packages/aria-connector/scripts/verify-codex-native-mirror.mjs
+//   exit 0 = both gates pass; exit 1 = any gap detected
+//
+// Designed to be wired into pre-commit / CI / aria-install-hooks so this
+// class of regression cannot ship again silently.
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { homedir } from 'node:os';
+
+const HOME = homedir();
+const REPO = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..');
+
+// Four mirror roots that must agree. Each entry maps a relative-path key to
+// its absolute root. Files in the closure must exist + match sha256 at every
+// applicable root. Some roots only host a subset (e.g. ~/.codex/ doesn't host
+// hive-wal-consumer.mjs because it's a Claude-only cross-CLI add).
+const MIRROR_ROOTS = {
+  canonical: path.join(REPO, 'ops', 'claude-hooks', 'codex-native'),
+  packages:  path.join(REPO, 'packages', 'aria-connector', 'hooks', 'codex-native'),
+  deploy:    path.join(HOME, '.aria', 'runtime', 'hooks', 'codex-native'),
+  codex:     path.join(HOME, '.codex', 'hooks'),
+};
+
+// Top-level hook entry points — these are loaded by config.toml / settings.json.
+// Each is a closure root from which we walk imports.
+const HOOK_ENTRYPOINTS = [
+  'aria-userprompt-submit.mjs',
+  'aria-pre-tool-use.mjs',
+  'aria-post-tool-use.mjs',
+  'aria-stop.mjs',
+  'aria-harness-ticker-sidecar.mjs',
+  'aria-live-ticker.mjs',
+  'atlas-session-context.mjs',
+];
+
+// Files that exist only on the Claude side (cross-CLI fleet visibility add);
+// they don't need to be present at ~/.codex/.
+const CLAUDE_ONLY = new Set([
+  'aria-hive-wal-consumer.mjs',
+  'lib/hive-wal-consumer.mjs',
+]);
+
+// Sibling-lib paths some hooks import via `../../lib/X.mjs`. These resolve
+// OUTSIDE codex-native/ so each mirror root has a sibling location:
+//   canonical: ops/claude-hooks/lib/
+//   packages:  packages/aria-connector/hooks/lib/
+//   deploy:    ~/.aria/runtime/hooks/lib/
+//   codex:     ~/.codex/lib/  (note: not ~/.codex/hooks/lib/)
+const SIBLING_LIB_ROOTS = {
+  canonical: path.join(REPO, 'ops', 'claude-hooks', 'lib'),
+  packages:  path.join(REPO, 'packages', 'aria-connector', 'hooks', 'lib'),
+  deploy:    path.join(HOME, '.aria', 'runtime', 'hooks', 'lib'),
+  codex:     path.join(HOME, '.codex', 'lib'),
+};
+
+const IMPORT_RX = /^import[\s\S]*?from\s+['"]([^'"]+)['"]\s*;?$/gm;
+
+function sha256(filepath) {
+  if (!existsSync(filepath)) return null;
+  const buf = readFileSync(filepath);
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Walk imports from `entryAbs` (absolute path) and return the closure set
+ * keyed by repo-relative path (relative to the canonical root or sibling lib
+ * root). Each value is { kind: 'codex-native' | 'sibling-lib', absPath }.
+ */
+function walkImportClosure(entryAbs, canonicalRoot, siblingLibRoot, seen = new Map()) {
+  if (seen.has(entryAbs)) return seen;
+  if (!existsSync(entryAbs)) return seen;
+  seen.set(entryAbs, null);
+  const body = readFileSync(entryAbs, 'utf8');
+  for (const m of body.matchAll(IMPORT_RX)) {
+    const spec = m[1];
+    if (!spec.startsWith('.')) continue; // bare imports are node-core or npm; skip
+    const resolved = path.resolve(path.dirname(entryAbs), spec);
+    walkImportClosure(resolved, canonicalRoot, siblingLibRoot, seen);
+  }
+  return seen;
+}
+
+function relativizeToMirror(absPath) {
+  // Determine if file lives under codex-native/ or under sibling-lib/
+  for (const [root, abs] of Object.entries(MIRROR_ROOTS)) {
+    if (absPath.startsWith(abs + path.sep)) {
+      return { kind: 'codex-native', rootKey: root, rel: path.relative(abs, absPath) };
+    }
+  }
+  for (const [root, abs] of Object.entries(SIBLING_LIB_ROOTS)) {
+    if (absPath.startsWith(abs + path.sep)) {
+      return { kind: 'sibling-lib', rootKey: root, rel: path.relative(abs, absPath) };
+    }
+  }
+  return null;
+}
+
+// ===== GAP 1: closure walk + byte-identical verification =====
+console.log('=== GAP 1: dependency-closure mirror verification ===');
+const closure = new Map(); // key: `${kind}::${rel}` → set of present rootKeys
+let gap1Fail = 0;
+
+for (const hook of HOOK_ENTRYPOINTS) {
+  const canonAbs = path.join(MIRROR_ROOTS.canonical, hook);
+  if (!existsSync(canonAbs)) {
+    console.log(`  WARN  canonical missing: ${hook}`);
+    continue;
+  }
+  const seen = walkImportClosure(canonAbs, MIRROR_ROOTS.canonical, SIBLING_LIB_ROOTS.canonical);
+  for (const abs of seen.keys()) {
+    const r = relativizeToMirror(abs);
+    if (!r) continue;
+    const key = `${r.kind}::${r.rel}`;
+    if (!closure.has(key)) closure.set(key, { kind: r.kind, rel: r.rel, expected: new Set(), shas: {} });
+  }
+}
+
+// For each closure file, check existence + sha across all 4 roots
+for (const [key, info] of closure) {
+  const roots = info.kind === 'codex-native' ? MIRROR_ROOTS : SIBLING_LIB_ROOTS;
+  const shas = {};
+  const missing = [];
+  for (const [rootKey, rootDir] of Object.entries(roots)) {
+    if (CLAUDE_ONLY.has(info.rel) && rootKey === 'codex') continue; // Claude-only files OK to skip on Codex
+    const filepath = path.join(rootDir, info.rel);
+    const sha = sha256(filepath);
+    if (sha === null) {
+      missing.push(rootKey);
+    } else {
+      shas[rootKey] = sha;
+    }
+  }
+  const uniqueShas = new Set(Object.values(shas));
+  if (missing.length > 0) {
+    console.log(`  GAP   ${info.rel.padEnd(50)} missing at: ${missing.join(', ')}`);
+    gap1Fail++;
+  } else if (uniqueShas.size > 1) {
+    console.log(`  DIFF  ${info.rel.padEnd(50)} sha-mismatch across roots: ${JSON.stringify(shas)}`);
+    gap1Fail++;
+  } else {
+    console.log(`  ok    ${info.rel.padEnd(50)} sha=${[...uniqueShas][0].slice(0,12)} (${Object.keys(shas).length} roots)`);
+  }
+}
+
+if (gap1Fail === 0) {
+  console.log(`Gap 1: PASS (${closure.size} closure files byte-identical across applicable mirror roots)`);
+} else {
+  console.log(`Gap 1: FAIL (${gap1Fail} closure files missing or sha-mismatched)`);
+}
+
+// ===== GAP 2: live readback on every hook entrypoint =====
+console.log();
+console.log('=== GAP 2: live-readback on every hook entrypoint ===');
+
+const SYNTHETIC = {
+  UserPromptSubmit: { hook_event_name: 'UserPromptSubmit', session_id: 'verify-mirror', user_prompt: 'probe' },
+  PreToolUse: { hook_event_name: 'PreToolUse', session_id: 'verify-mirror', tool_name: 'Bash', tool_input: { command: 'ls' } },
+  PostToolUse: { hook_event_name: 'PostToolUse', session_id: 'verify-mirror', tool_name: 'Bash', tool_input: { command: 'ls' }, tool_response: { stdout: 'x', stderr: '', exit_code: 0 } },
+  Stop: { hook_event_name: 'Stop', session_id: 'verify-mirror', transcript_path: '/tmp/nonexistent.jsonl' },
+};
+
+const HOOK_TO_EVENT = {
+  'aria-userprompt-submit.mjs': 'UserPromptSubmit',
+  'aria-pre-tool-use.mjs': 'PreToolUse',
+  'aria-post-tool-use.mjs': 'PostToolUse',
+  'aria-stop.mjs': 'Stop',
+  'aria-harness-ticker-sidecar.mjs': 'UserPromptSubmit', // sidecar reads state, any event is fine
+  'aria-live-ticker.mjs': 'UserPromptSubmit',
+  'atlas-session-context.mjs': 'UserPromptSubmit',
+};
+
+const READBACK_ROOTS = {
+  'deploy (Claude)': MIRROR_ROOTS.deploy,
+  'codex (live)':    MIRROR_ROOTS.codex,
+};
+
+let gap2Fail = 0;
+const CRASH_RX = /SyntaxError|TypeError|ReferenceError|ERR_MODULE_NOT_FOUND/;
+
+for (const [rootLabel, rootDir] of Object.entries(READBACK_ROOTS)) {
+  for (const hook of HOOK_ENTRYPOINTS) {
+    if (CLAUDE_ONLY.has(hook) && rootLabel.includes('codex')) continue;
+    const filepath = path.join(rootDir, hook);
+    if (!existsSync(filepath)) {
+      console.log(`  WARN  ${rootLabel.padEnd(18)} ${hook.padEnd(35)} missing (skip)`);
+      continue;
+    }
+    const eventName = HOOK_TO_EVENT[hook] || 'UserPromptSubmit';
+    const payload = JSON.stringify(SYNTHETIC[eventName]);
+    const env = {
+      ...process.env,
+      HOOK_EVENT_NAME: eventName,
+      ARIA_HOOK_SURFACE: rootLabel.includes('codex') ? 'codex' : 'claude',
+      // AI-12107 — structural short-circuit honored by runtime-client.mjs.
+      // runtimePost + LocalHarnessPacketClient.getHarnessPacket detect this
+      // env and return shape-compatible no-ops, skipping HTTP I/O. Hooks
+      // exercise their import path (the actual readback goal) but complete
+      // in milliseconds. No wall-clock timeout needed; the no-timeouts
+      // doctrine is honored — only structural signals decide pass/fail.
+      ARIA_HOOK_VERIFIER_MODE: '1',
+    };
+    const result = spawnSync('node', [filepath], { input: payload, env, encoding: 'utf8' });
+    const stderr = result.stderr || '';
+    const crashType = stderr.match(CRASH_RX);
+    if (result.status === 0 && !crashType) {
+      console.log(`  ok    ${rootLabel.padEnd(18)} ${hook.padEnd(35)} exit=0`);
+    } else if (crashType) {
+      // Real import/runtime crash — the exact class this verifier exists to catch.
+      console.log(`  CRASH ${rootLabel.padEnd(18)} ${hook.padEnd(35)} exit=${result.status} ${crashType[0]}`);
+      const firstLine = stderr.split('\n').slice(0, 3).join(' | ').slice(0, 200);
+      console.log(`        stderr: ${firstLine}`);
+      gap2Fail++;
+    } else if (result.signal || result.status === null) {
+      // Timeout or signal — hook didn't crash on load, it just exceeded budget
+      // or got SIGTERM'd. Warn but don't fail; live readback proved the hook
+      // imports cleanly (otherwise the crash would have happened in ms, not 30s).
+      console.log(`  warn  ${rootLabel.padEnd(18)} ${hook.padEnd(35)} timeout/signal=${result.signal || 'null'} (imports clean, exceeds 30s budget — non-fatal)`);
+    } else {
+      // Non-zero exit with no crash signature — likely the hook itself
+      // chose to exit non-zero (e.g. hook protocol asks for hard-block).
+      // That's hook behavior, not a mirror bug — log but don't fail.
+      console.log(`  exit  ${rootLabel.padEnd(18)} ${hook.padEnd(35)} exit=${result.status} (hook-chosen non-zero, no crash signature — non-fatal)`);
+    }
+  }
+}
+
+if (gap2Fail === 0) {
+  console.log(`Gap 2: PASS (every hook entrypoint loaded + exited 0 with no crash signature)`);
+} else {
+  console.log(`Gap 2: FAIL (${gap2Fail} hook invocations crashed)`);
+}
+
+// ===== Final verdict =====
+console.log();
+const totalFail = gap1Fail + gap2Fail;
+if (totalFail === 0) {
+  console.log('codex-native mirror verifier: BOTH GATES PASS');
+  process.exit(0);
+} else {
+  console.log(`codex-native mirror verifier: FAIL — ${gap1Fail} closure gaps + ${gap2Fail} live-readback crashes`);
+  process.exit(1);
+}

package/skills/34-frameworks-unified/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: 34-frameworks-unified
+description: Use when a problem benefits from combining many strategic frameworks at once, especially for business analysis, marketing, sales, leadership, creative problem-solving, decision-making under uncertainty, or multi-perspective synthesis.
+---
+
+# 34 Frameworks Unified
+
+Read `/home/hamzaibrahim1/.claude/skills/34-frameworks-unified.md` for the full framework inventory and recombination model.
+
+Workflow:
+
+1. Identify the actual decision, strategy, or design problem.
+2. Load the source doc and select only the framework families that materially improve the answer.
+3. Synthesize across those lenses instead of producing isolated mini-analyses.
+4. Favor high-signal recombination over exhaustive enumeration.
+
+## 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/api-design/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: api-design
+description: REST, gRPC, and GraphQL API design patterns, versioning strategies, error contracts, pagination, rate limiting, and API lifecycle management. Use when the user designs a new API, reviews an API contract, asks about API versioning, needs RESTful resource modeling, evaluates gRPC vs REST, or designs request/response schemas. Do NOT use for database schema design — use database-design skill instead.
+---
+
+## What I Do
+
+- Design RESTful resource models: resource identification, HTTP method semantics, status code usage, HATEOAS when appropriate
+- Design gRPC service definitions: protobuf message design, service method semantics, streaming patterns
+- Design GraphQL schemas: type system, query/mutation design, resolver patterns, N+1 mitigation
+- Define API versioning strategies: URL path, header-based, query parameter, content negotiation
+- Design error contracts: structured error responses, error codes, machine-readable and human-readable messages
+- Define pagination patterns: offset-based, cursor-based, keyset pagination, Relay connection spec
+- Design rate limiting and quota models: token bucket, sliding window, response headers
+- Specify authentication and authorization patterns at the API boundary
+- Design API lifecycle: alpha → beta → stable → deprecated → sunset, with migration guides
+- Define idempotency patterns and safe retry semantics
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "design an API for"
+- "what should the REST endpoints be"
+- "version this API"
+- "gRPC vs REST for"
+- "design the protobuf messages"
+- "GraphQL schema for"
+- "API error handling"
+- "pagination strategy"
+- "rate limiting design"
+- "API contract"
+- "design the request/response"
+- "idempotency for"
+- "backward compatible change"
+
+## When NOT to Use Me
+
+- Do not use for database schema design (use database-design skill)
+- Do not use for system-level architecture decisions (use architecture-decision skill)
+- Do not use for implementing API clients or servers — this is design guidance only
+- Do not use for security-specific API concerns like OAuth2 flows (use security-review skill)
+- Do not use when the API is already stable and well-documented — no unnecessary redesign
+
+## Workflow
+
+1. **Define the resource model**
+   - Identify the domain entities and their relationships
+   - Map entities to REST resources or GraphQL types
+   - Define the URL structure: collections, singleton resources, sub-resources
+   - Name resources with plural nouns, use kebab-case for multi-word resources
+
+2. **Design operations**
+   - Map CRUD to HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE (delete)
+   - Define custom actions as sub-resources: `POST /orders/{id}/cancel`
+   - For gRPC: define unary, server-streaming, client-streaming, bidirectional methods
+   - For GraphQL: define queries (reads), mutations (writes), subscriptions (events)
+
+3. **Design request/response schemas**
+   - Use consistent envelope or bare responses — pick one and stick with it
+   - Define field naming convention: snake_case (REST/JSON), camelCase (GraphQL), snake_case (protobuf)
+   - Specify required vs optional fields explicitly
+   - Define validation constraints (length, range, format) at the schema level
+   - Use semantic types: UUID, ISO 8601 dates, ISO 4217 currencies, not raw strings
+
+4. **Design error responses**
+   - Use RFC 7807 Problem Details for REST: `type`, `title`, `status`, `detail`, `instance`
+   - For gRPC: use standard status codes with rich error details via `google.rpc.Status`
+   - For GraphQL: use the `errors` array with `extensions.code` for machine-readable codes
+   - Define a finite error code enum — never return raw exception messages to clients
+
+5. **Define pagination**
+   - For REST: prefer cursor-based pagination for mutable/large datasets
+   - Include `next` and `prev` links in response, not just raw cursors
+   - For GraphQL: implement the Relay Connection spec (`edges`, `node`, `pageInfo`, `cursor`)
+   - For gRPC: use `page_token` field pattern with `next_page_token` in response
+
+6. **Versioning strategy**
+   - Prefer URL path versioning (`/v1/`, `/v2/`) for REST unless you need fine-grained versioning
+   - For gRPC: version the package name (`com.example.api.v1`)
+   - For GraphQL: avoid versioning — use schema evolution with `@deprecated` directives
+   - Define a deprecation timeline: announce → warn → block → remove
+
+7. **Document the contract**
+   - REST: OpenAPI 3.x specification
+   - gRPC: protobuf files with rich comments (used by protoc-gen-doc)
+   - GraphQL: schema introspection with descriptions on every type and field
+   - Include request/response examples for every endpoint
+
+## References
+
+- RFC 7807 Problem Details: https://datatracker.ietf.org/doc/html/rfc7807
+- JSON:API spec: https://jsonapi.org/
+- Google API Design Guide: https://cloud.google.com/apis/design
+- Microsoft REST API Guidelines: https://github.com/microsoft/api-guidelines
+- gRPC API design: https://grpc.io/docs/guides/design/
+- GraphQL best practices: https://graphql.org/learn/best-practices/
+- Relay Connection spec: https://relay.dev/graphql/connections.htm
+- Stripe API as reference design: https://stripe.com/docs/api
+
+## Output & Organization
+
+- API contracts saved in `docs/api/` or alongside service code in `api/`
+- OpenAPI specs: `openapi.yaml` or `openapi.json`
+- Protobuf: `proto/<service>/v1/<service>.proto`
+- GraphQL: `schema.graphql` with descriptions
+- Include a README.md in the API docs directory explaining the versioning and deprecation policy
+## 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/architecture-decision/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: architecture-decision
+description: Architecture Decision Records (ADR), architectural patterns, trade-off analysis, system design, and technology selection. Use when the user asks about architecture decisions, wants to evaluate design options, needs a decision record, asks "should we use X or Y", talks about system design, microservices vs monolith, or needs to document an architectural choice. Do NOT use for implementation-level code decisions — this is for system-level architecture only.
+---
+
+## What I Do
+
+- Guide the creation of Architecture Decision Records (ADRs) following the Michael Nygard format
+- Evaluate architectural trade-offs between competing approaches with structured comparison
+- Recommend technology selections with explicit rationale, risks, and mitigation strategies
+- Assess system design patterns: microservices, monolith, modular monolith, event-driven, CQRS, hexagonal/ports-adapters, layered
+- Identify architectural fitness functions and quality attribute scenarios
+- Evaluate scalability, reliability, maintainability, and cost implications of architectural choices
+- Design incremental migration paths and strangler fig adoption strategies
+- Assess coupling, cohesion, and Conway's Law implications
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "what architecture should we use for"
+- "should we use X or Y" (technology/framework/pattern comparison)
+- "create an ADR for"
+- "document this architectural decision"
+- "evaluate the trade-offs"
+- "design the system architecture"
+- "monolith vs microservices"
+- "how should we structure this"
+- "migration strategy for"
+- "scaling concerns"
+- "technology stack for"
+- "system design" (as a topic, not interview prep specifically)
+
+## When NOT to Use Me
+
+- Do not use for implementation-level code patterns (use refactoring skill instead)
+- Do not use for API-level endpoint design decisions (use api-design skill instead)
+- Do not use for database schema decisions (use database-design skill instead)
+- Do not use for CI/CD pipeline design (use ci-cd-pipeline skill instead)
+- Do not use when a decision has already been made and documented
+- Do not use for small, reversible, low-impact choices
+
+## Workflow
+
+1. **Understand the decision context**
+   - Identify the problem being solved, the constraints (technical, organizational, temporal), and the stakeholders
+   - Determine the scope: system-level, subsystem-level, or component-level architecture
+
+2. **Enumerate options**
+   - List at least 3 options, including "do nothing / status quo" when relevant
+   - For each option, describe the approach in concrete terms
+   - Avoid straw-man options — represent each option fairly
+
+3. **Evaluate trade-offs**
+   - For each option, assess: scalability, complexity, cost, risk, team capability, time-to-market, maintainability, operational overhead
+   - Use a structured comparison: table or weighted matrix when appropriate
+   - Identify each option's "hard parts" — what will cause the most pain
+
+4. **Make a recommendation**
+   - State the recommended approach clearly
+   - Provide the rationale: why this wins over the alternatives
+   - Explicitly state the risks and assumptions
+   - Define rejection criteria: what would make you reverse this decision
+
+5. **Document as an ADR**
+   - Title: short noun phrase (e.g., "ADR-001: Use PostgreSQL as primary database")
+   - Status: Proposed → Accepted → Deprecated → Superseded
+   - Context: the problem, forces, constraints
+   - Decision: the chosen approach, stated clearly
+   - Consequences: what becomes easier, harder, and the resulting trade-offs
+   - Save ADRs in `docs/adr/` or `.adr/` directory with sequential numbering
+
+6. **Define migration path**
+   - If replacing an existing system, outline incremental migration steps
+   - Specify how to validate each step before proceeding
+   - Identify rollback points
+
+## References
+
+- Michael Nygard's ADR format: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
+- ADR GitHub organization: https://adr.github.io/
+- ThoughtWorks Technology Radar for technology evaluation: https://www.thoughtworks.com/radar
+
+## Output & Organization
+
+- ADRs saved as `docs/adr/NNNN-title-with-hyphens.md`
+- Each ADR is self-contained and immutable once accepted
+- Superseded ADRs reference their replacement
+- Keep ADRs under 2 pages — be concise
+## 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.