@agentikos/omega-os 0.2.0 → 0.19.6

package/omega/Agentik_SSOT/skills/a11yaudit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: a11yaudit
+description: Forensic accessibility audit — Can EVERYONE use it — keyboard-only, screen reader, low vision, reduced motion?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/a11yaudit", "audit accessibility", or asks to verify the accessibility health of the project.
+when_to_use: User says /a11yaudit, audit accessibility, check accessibility, verify accessibility, is accessibility healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# a11yaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Can EVERYONE use it — keyboard-only, screen reader, low vision, reduced motion?
+
+You are running the a11yaudit forensic audit. Apply the **Gestalt-Popper
+doctrine**: identify the hinge point, scrutinise it 10x, then assume
+every name is a CLAIM and look for the divergence between the claim and
+the reality. Bias toward FAIL. A perfect score is earned by finding zero
+falsifiable claims, never by absence of effort.
+
+## Run
+
+The audit is one engine call — gather (deterministic) + falsify (agentic)
++ optional fix-dispatch (capped) + re-audit. Invoke the unified pipeline:
+
+```bash
+omega audit run a11yaudit $args
+```
+
+Common options:
+
+| Flag | Effect |
+|---|---|
+| `--scope <path>` | scope the audit (file or directory) |
+| `--fix` | after analysing, batch findings + dispatch up to N workers + re-audit |
+| `--max-workers N` | cap parallel fix workers (default 3) |
+| `--min-severity high` | only batch + fix findings at or above this severity |
+
+Read-only by default. Add `--fix` to enable the dispatch + re-audit loop.
+
+## Phases under investigation
+
+The agentic pass walks each phase below and emits structured findings
+(claim vs. reality). Every PASS must cite ≥3 concrete checks.
+
+### 1. hinge-keyboard-navigation
+
+HINGE — disconnect the mouse and complete the primary user journey keyboard-only; logical tab order matching visual flow, no tabindex>0, no non-interactive element focusable; every button activates with Enter AND Space, links with Enter, Escape closes overlays.
+
+### 2. keyboard-traps-focus-visibility
+
+Focus can always escape every modal, dropdown, menu and date picker (no infinite tab loop); focus indicator ALWAYS visible, >=2px and >=3:1 contrast, in light/dark/high-contrast; no outline:none without a replacement.
+
+### 3. wcag-aa-compliance
+
+Per page verify WCAG 2.1 AA across the four principles — Perceivable, Operable, Understandable, Robust; lang attribute, valid HTML with no duplicate IDs, reflow at 320px, text resize to 200%; treat the 70% of failures automation misses as the real work.
+
+### 4. screen-reader-semantics
+
+Page title, headings, landmarks and list/table structure announced; buttons announce name+role, inputs announce label+type+state; reading order matches visual layout; nothing meaningful hidden from the screen reader, nothing decorative announced.
+
+### 5. aria-correctness
+
+First rule of ARIA — if native HTML can do it, ARIA is wrong; custom widgets have correct roles with required children; aria-expanded/selected/checked/current reflect real state; aria-labelledby/describedby/controls reference existing visible elements; aria-hidden never hides visible content.
+
+### 6. semantic-elements
+
+Interactive things are real <button>/<a>/<input>, not <div onClick>; landmark elements (<main> once, <nav>, <header>, <footer>) present, labelled when repeated, and wrap all visible content with no orphans.
+
+### 7. color-contrast
+
+Normal text >=4.5:1, large text >=3:1 against every background it sits on (including over images/gradients and placeholder text); UI component borders, focus rings and meaningful icons >=3:1; verify in dark mode and forced-colors.
+
+### 8. color-independence
+
+No information conveyed by colour alone — links distinguishable without colour (underline/weight), required fields marked with text/asterisk, errors carry icon+text not just red; grayscale the page and confirm nothing is lost.
+
+### 9. form-labels-and-instructions
+
+Every input has a programmatic label (label/aria-label/aria-labelledby), placeholder is never the only label; correct input types and autocomplete on personal-data fields; required fields marked visually AND with aria-required; instructions precede the form; related inputs grouped with fieldset/legend.
+
+### 10. error-announcements
+
+Inline errors associated via aria-describedby/aria-errormessage and announced without reload, field marked aria-invalid; on submit failure an error summary appears, focus moves to it, error count announced; success confirmed via aria-live; destructive actions confirm and warn of data loss.
+
+### 11. alt-text
+
+Informative images have descriptive alt conveying content+purpose; decorative images have alt="" (empty, not missing) and decorative icons aria-hidden; functional/image links/buttons describe the destination or action; complex charts have a text or data-table alternative; SVGs labelled or hidden.
+
+### 12. heading-hierarchy-skip-nav
+
+Exactly one <h1>, no skipped levels, headings describe content and are not styled-div fakes; a 'Skip to main content' link is the first focusable element, visible on focus, and lands on a valid landmark/heading.
+
+### 13. focus-management
+
+Focus starts at a logical position on load and moves to new content on SPA route change (with page-title update); modals move focus in on open and return it to the trigger on close; deleted content moves focus to a logical neighbour; focus never silently lost to <body>.
+
+### 14. motion-and-touch-targets
+
+@media (prefers-reduced-motion: reduce) honoured by CSS and JS animations; no auto-playing audio ever, video/carousels have pause, nothing flashes >3x/sec; interactive targets >=44x44px CSS with >=8px spacing, checked at the smallest mobile viewport.
+
+## Falsification rules
+
+Automated tools catch ~30% of failures — a "0 violations" report means 70% are INVISIBLE to automation, not absent. Every PASS must cite >=3 concrete manual checks (keyboard-only walkthrough of the flow, computed contrast ratio, grayscale test, prefers-reduced-motion toggle) with verbatim observations. Categorise findings as VISUAL-vs-SEMANTIC, MOUSE-vs-KEYBOARD, SIGHTED-vs-SCREEN-READER, DESKTOP-vs-MOBILE or DEFAULT-vs-PREFERENCE. An axe-core contrast finding near the 4.5 threshold must be confirmed by computing the exact ratio. Bias toward FAIL — the excluded users never complained.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history a11yaudit`)
+Agentik_Runtime/sessions/${CLAUDE_SESSION_ID}/.done.json   (this turn)
+```
+
+The `.done.json` schema:
+
+```json
+{
+  "status": "done_clean" | "pending" | "failed",
+  "summary": "<one-paragraph verdict>",
+  "artifacts": {
+    "audit": "a11yaudit",
+    "score": 0-100,
+    "verified": bool,
+    "findings": [...],
+    "fix_plan": [...],
+    "dispatches": [...],
+    "reaudit_score": 0-100  // only when --fix was used
+  }
+}
+```
+
+## Hard rules (don't break these)
+
+1. **No fake "done".** First Law: only runtime tells the truth. If the
+   gather phase fails or the agentic verdict scores below the threshold,
+   you have NOT verified — set status to `pending` or `failed`.
+2. **Cap parallelism.** ≤ 3 fix workers at a time. The
+   batcher enforces this; do not call out to other dispatch mechanisms.
+3. **No worker per finding.** Findings are clustered by file footprint and
+   severity. One worker handles one disjoint batch.
+4. **Re-audit confirms.** After fixes land, the pipeline re-runs the same
+   gather + agentic phases. If the score did not improve, escalate honestly.
+5. **History is the trend.** `omega audit history a11yaudit` shows whether the
+   codebase is improving over time on this dimension. Use it to decide
+   whether to push for `--fix` again.
+
+## Why this audit exists
+
+The 18 forensic audits are the OmegaOS verification layer. Claude's
+"I'm done" claims used to be unverified. With these audits running as
+the gate, completion is **derived from observable facts**, not declared
+by the worker. Run this audit any time someone (human or agent) claims
+the accessibility dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/a11yaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`

package/omega/Agentik_SSOT/skills/apiaudit/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: apiaudit
+description: Forensic api audit — Does the API work CORRECTLY, CONSISTENTLY and SAFELY for every caller?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/apiaudit", "audit api", or asks to verify the api health of the project.
+when_to_use: User says /apiaudit, audit api, check api, verify api, is api healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# apiaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Does the API work CORRECTLY, CONSISTENTLY and SAFELY for every caller?
+
+You are running the apiaudit forensic audit. Apply the **Gestalt-Popper
+doctrine**: identify the hinge point, scrutinise it 10x, then assume
+every name is a CLAIM and look for the divergence between the claim and
+the reality. Bias toward FAIL. A perfect score is earned by finding zero
+falsifiable claims, never by absence of effort.
+
+## Run
+
+The audit is one engine call — gather (deterministic) + falsify (agentic)
++ optional fix-dispatch (capped) + re-audit. Invoke the unified pipeline:
+
+```bash
+omega audit run apiaudit $args
+```
+
+Common options:
+
+| Flag | Effect |
+|---|---|
+| `--scope <path>` | scope the audit (file or directory) |
+| `--fix` | after analysing, batch findings + dispatch up to N workers + re-audit |
+| `--max-workers N` | cap parallel fix workers (default 3) |
+| `--min-severity high` | only batch + fix findings at or above this severity |
+
+Read-only by default. Add `--fix` to enable the dispatch + re-audit loop.
+
+## Phases under investigation
+
+The agentic pass walks each phase below and emits structured findings
+(claim vs. reality). Every PASS must cite ≥3 concrete checks.
+
+### 1. endpoint-inventory
+
+Enumerate every route with its HTTP method; classify public vs authenticated vs admin; flag debug/test routes live in prod, duplicate routes, and verbs-in-paths breaking REST nouns.
+
+### 2. hinge-authentication
+
+HINGE — for EVERY endpoint verify auth is enforced BEFORE any data access; send no-token / expired / malformed / other-user's-token; any 200 with data instead of 401/403 is a critical breach. Catch routes accidentally public via missing middleware.
+
+### 3. hinge-authorization
+
+HINGE — test every endpoint with every role; admin routes reject regular users, user routes reject guests; resource-level ownership enforced (no IDOR); no privilege escalation via body params; field-level authz on sensitive fields; no mass assignment.
+
+### 4. input-validation
+
+Every parameter on every endpoint — type, boundary (min/max length, range, array size, nesting depth), format (email/url/uuid), enum whitelist; Content-Type matches body; injection chars (SQL, NoSQL $ops, ../, shell) rejected.
+
+### 5. contract-compliance
+
+Response envelope identical across endpoints (data/errors/meta); ISO-8601 dates; consistent null-vs-missing handling; no breaking changes (field removal, type change, new required field); GraphQL depth/complexity limits, introspection off in prod.
+
+### 6. status-codes
+
+Correct codes per outcome — 201+Location on create, 204 on delete, 400 validation, 401 unauthenticated, 403 unauthorised, 404 missing, 409 conflict, 422 semantic, 429 rate-limited; never 200 for errors, never 500 for client mistakes.
+
+### 7. error-format
+
+Every error has status + machine-parseable code + message; validation errors list ALL invalid fields; no stack traces / DB errors / internal paths leaked; no user enumeration (same error for existing vs non-existing); Retry-After on 429.
+
+### 8. rate-limiting
+
+Global per-IP/user limit plus per-endpoint limits on expensive and auth operations; X-RateLimit-* and Retry-After headers present; tiered fairness for authenticated/paid callers; limits not bypassable via header spoofing.
+
+### 9. pagination
+
+Every list endpoint paginated with a sane default and enforced max page size; cursor- or offset-based consistently; page metadata (cursor/total/hasNext) returned; empty page returns [] not 404.
+
+### 10. idempotency
+
+GET/HEAD/OPTIONS truly side-effect free; PUT and DELETE idempotent on repeat; POST supports idempotency keys for money/critical ops; timeout+retry never creates duplicates or corrupts state.
+
+### 11. n-plus-one-perf
+
+Count DB queries per API call — find N+1 (list endpoint issuing one query per row); dataloader/batching for GraphQL, eager loading for ORM relations; no SELECT *; response times within p95<1s budget.
+
+### 12. cors-webhooks
+
+CORS Allow-Origin is a specific allowlist (no wildcard with credentials), only needed methods/headers; webhooks verify HMAC signature, enforce HTTPS, include event type + timestamp, retry with backoff.
+
+### 13. versioning-deprecation
+
+API version communicated consistently; backward compatibility preserved or sunset announced; deprecated endpoints emit Deprecation/Sunset headers, still function during the window, and point callers to the replacement.
+
+## Falsification rules
+
+"It works in Postman" proves nothing — Postman has the token, correct headers and the happy path. Every PASS must cite >=3 concrete requests run (no auth, wrong role, malformed body, boundary value, concurrent calls) with verbatim status + body. Categorise findings as HAPPY-vs-EDGE, ADMIN-vs-USER, SINGLE-vs-CONCURRENT, SPEC-vs-REALITY or POSTMAN-vs-PRODUCTION. A static scan reporting an "unauthenticated endpoint" must be confirmed by reading the handler — auth may live in middleware the scan cannot see. Bias toward FAIL.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history apiaudit`)
+Agentik_Runtime/sessions/${CLAUDE_SESSION_ID}/.done.json   (this turn)
+```
+
+The `.done.json` schema:
+
+```json
+{
+  "status": "done_clean" | "pending" | "failed",
+  "summary": "<one-paragraph verdict>",
+  "artifacts": {
+    "audit": "apiaudit",
+    "score": 0-100,
+    "verified": bool,
+    "findings": [...],
+    "fix_plan": [...],
+    "dispatches": [...],
+    "reaudit_score": 0-100  // only when --fix was used
+  }
+}
+```
+
+## Hard rules (don't break these)
+
+1. **No fake "done".** First Law: only runtime tells the truth. If the
+   gather phase fails or the agentic verdict scores below the threshold,
+   you have NOT verified — set status to `pending` or `failed`.
+2. **Cap parallelism.** ≤ 3 fix workers at a time. The
+   batcher enforces this; do not call out to other dispatch mechanisms.
+3. **No worker per finding.** Findings are clustered by file footprint and
+   severity. One worker handles one disjoint batch.
+4. **Re-audit confirms.** After fixes land, the pipeline re-runs the same
+   gather + agentic phases. If the score did not improve, escalate honestly.
+5. **History is the trend.** `omega audit history apiaudit` shows whether the
+   codebase is improving over time on this dimension. Use it to decide
+   whether to push for `--fix` again.
+
+## Why this audit exists
+
+The 18 forensic audits are the OmegaOS verification layer. Claude's
+"I'm done" claims used to be unverified. With these audits running as
+the gate, completion is **derived from observable facts**, not declared
+by the worker. Run this audit any time someone (human or agent) claims
+the api dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/apiaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`

package/omega/Agentik_SSOT/skills/audit-orchestrator.md

@@ -0,0 +1,212 @@
+---
+name: audit-orchestrator
+description: >
+  Intelligent audit orchestrator — detects project type + user intent, recommends
+  optimal audits with 3 power levels (Quick/Standard/Forensic). Use when user
+  says "/audit", "what should I audit", "full audit", "audit my project",
+  "audit fast", "audit deep", "find issues", "improve quality", "production
+  ready check", "ship-ready audit". Auto-detects project stack and intent
+  keywords (speed, security, design, content, accessibility, full) to pick
+  best 1-N audits. Dispatches in parallel waves. Reads results from
+  audits/.{name}audit/verdict.json after each run.
+disable-model-invocation: false
+---
+
+# /audit-orchestrator — Intelligent Audit Selection + Power Levels
+
+You are the **audit conductor**. Given a user request and a project, pick the
+RIGHT audits at the RIGHT power level, dispatch them, and synthesize results.
+
+## How to invoke
+
+```bash
+/audit-orchestrator               # interactive: ask user what to audit
+/audit-orchestrator full          # run all 17 audits in parallel
+/audit-orchestrator quick         # top 5 most-impactful audits at Quick level
+/audit-orchestrator standard      # smart selection at Standard level (default)
+/audit-orchestrator forensic      # deep Gestalt-Popper on selected audits
+/audit-orchestrator security      # secaudit + apiaudit + dataaudit
+/audit-orchestrator performance   # perfaudit + seoaudit
+/audit-orchestrator design        # uiuxaudit + motionaudit + a11yaudit + copyaudit
+```
+
+## The 17 audits in the Quality Arsenal
+
+| Audit | Domain | When to pick |
+|---|---|---|
+| `/codeaudit` | Code architecture | New codebase, refactor, technical debt |
+| `/secaudit` | Security (OWASP) | Pre-prod, payment handling, auth surfaces |
+| `/uiuxaudit` | Design quality | Visual consistency, design system audit |
+| `/flowaudit` | User journeys | Onboarding, conversion drops, dead-ends |
+| `/debugaudit` | Runtime bugs | Console errors, broken features, smoke test |
+| `/featureaudit` | Completeness | PRD validation, ship-readiness, "what's missing" |
+| `/perfaudit` | Core Web Vitals | Slow site, lighthouse improvement |
+| `/a11yaudit` | WCAG 2.1 AA | Accessibility, screen readers, contrast |
+| `/seoaudit` | Discoverability | Search ranking, GEO/AEO, schema markup |
+| `/dataaudit` | Schema integrity | Orphaned records, migrations, RGPD |
+| `/apiaudit` | API contracts | Endpoint quality, auth matrix, rate limits |
+| `/copyaudit` | Messaging | Claims vs reality, CTA, tone |
+| `/dxaudit` | Dev experience | README quality, onboarding new devs |
+| `/motionaudit` | Animation design | Transitions, easing, motion brand DNA |
+| `/automationaudit` | Cron/scripts | Daemon health, scheduled tasks reliability |
+| `/logicaudit` | Architecture | Algorithm efficiency, redundant logic |
+| `/retentionaudit` | Product/CPO | Feature opportunities, RICE roadmap (READ-ONLY) |
+
+## The 3 Power Levels
+
+### ⚡ Level 1 — Quick (5-15 min)
+- Top 5 critical findings only
+- Skip Plan + Fix phases
+- Output: `audits/.{name}audit/quick-report.md` (no verdict.json scoring)
+- Use case: gut-check before a meeting, fast triage
+
+### 🎯 Level 2 — Standard (30-60 min, DEFAULT)
+- Full phases: Audit → Plan → Fix → Re-audit
+- Score normalized /100
+- Output: complete `audits/.{name}audit/verdict.json` + reports
+- Use case: regular quality cycle, pre-PR validation
+
+### 🔬 Level 3 — Forensic (1-4h per audit)
+- Full Gestalt-Popper protocol, all phases extended
+- Auto-fix every finding P0/P1/P2
+- Re-audit cycles until 100/100 (or 3 cycle cap)
+- Output: forensic-grade with falsification proofs + telemetry
+- Use case: pre-launch, security/compliance gate, "make it bulletproof"
+
+## Smart Selection Algorithm
+
+When user says ambiguous request like "audit my project":
+
+```
+1. DETECT PROJECT TYPE
+   - Check package.json: React/Next.js/Vue → UI audits relevant
+   - Check requirements.txt/pyproject.toml: Python → no motion/uiux
+   - Check .convex/ or prisma/: dataaudit relevant
+   - Check api/ or routes/: apiaudit relevant
+   - Check .github/workflows/: dxaudit + automationaudit
+   - No src/ but docs/: feature/copy/seo only (docs project)
+
+2. PARSE INTENT KEYWORDS (English + French)
+   - "speed/fast/lent/lenteur" → perfaudit (+ seoaudit if web)
+   - "security/sec/vuln/secure/sécurité" → secaudit + apiaudit
+   - "design/visual/UI/UX/style" → uiuxaudit + motionaudit
+   - "content/copy/messaging/text" → copyaudit
+   - "accessibility/a11y/WCAG/handicap" → a11yaudit
+   - "API/endpoint/contract" → apiaudit + dataaudit
+   - "complete/missing/done/ship-ready" → featureaudit
+   - "code/quality/refactor" → codeaudit + logicaudit
+   - "retention/features/CPO/sticky" → retentionaudit
+   - "data/schema/migration" → dataaudit
+   - "automation/cron/scripts" → automationaudit
+   - "bug/error/broken/runtime" → debugaudit
+   - "redesign/refonte/dashboard" → refontaudit
+   - "full/all/everything/complet" → ALL 17 audits
+
+3. PICK POWER LEVEL
+   - Default: Standard (Level 2)
+   - User mentions "quick/fast/rapide" → Quick (Level 1)
+   - User mentions "deep/forensic/production/launch/100" → Forensic (Level 3)
+
+4. CHECK PROJECT MATURITY
+   - Empty src/ or fresh scaffold → skip code-focused audits, run featureaudit+copyaudit
+   - Mature codebase → all relevant
+   - Pre-launch → add secaudit + a11yaudit + perfaudit (the "go-live trio")
+```
+
+## Execution Plan Output
+
+Before dispatching, OUTPUT a plan like:
+
+```
+🎯 AUDIT PLAN — {project_name}
+
+Detected:
+  Stack:     Next.js + Tailwind + Convex
+  Maturity:  Production (12 months)
+  Intent:    "make sure it's secure before launch"
+
+Recommended (Power Level: Forensic):
+  1. /secaudit       (OWASP + payment surfaces — primary)
+  2. /apiaudit       (auth matrix + rate limits — secondary)
+  3. /dataaudit      (RGPD + orphan records — context for /apiaudit)
+  4. /a11yaudit      (legal compliance — go-live blocker)
+  5. /perfaudit      (CWV — go-live blocker)
+
+Estimated duration: 4-6h (parallel waves)
+Estimated tokens: ~800K
+
+Approve? [y/n/customize]
+```
+
+## Full Audit Mode
+
+When user says "full audit" / "audit complet" / "tous les audits":
+
+1. Dispatch ALL 17 audits in 3 parallel waves (file-safety partitioned):
+   - **Wave 1** (read-only, can parallel): codeaudit, logicaudit, dataaudit, apiaudit, seoaudit, featureaudit, retentionaudit, copyaudit, dxaudit
+   - **Wave 2** (after Wave 1 verdicts exist): secaudit (reads apiaudit), perfaudit, debugaudit, automationaudit
+   - **Wave 3** (UI bundle, after Wave 1): uiuxaudit, motionaudit, a11yaudit, flowaudit
+2. After all done, generate `audits/SYNTHESIS.md` aggregating scores
+3. Score the project: average /100 across all audits + flag any < 80
+4. Telegram report with verdict + button to view each detailed report
+
+## State Tracking
+
+Read `audits/SYNTHESIS.md` at start to know what's already done:
+
+```yaml
+last_full_audit: 2026-05-13T12:00:00Z
+scores:
+  codeaudit: 92/A
+  secaudit: 88/A
+  uiuxaudit: 91/S
+  ...
+status:
+  fresh:    [codeaudit, secaudit]  # < 7 days old
+  stale:    [perfaudit]            # 7-30 days old
+  expired:  [a11yaudit]            # > 30 days, recommend re-run
+```
+
+## Output Convention
+
+ALL audits MUST write to `audits/.{name}audit/` (the canonical post-2026-05-13
+location). Never to `./.{name}audit/` at project root. The new audit-orchestrator
++ audit-tracker skills assume this canonical path.
+
+## Anti-patterns
+
+- ❌ Running `/codeaudit` when project has no source code (use /dxaudit instead)
+- ❌ Running `/motionaudit` on CLI/library project (it ABORTS automatically)
+- ❌ Forensic level on every audit (token waste; use Standard unless go-live)
+- ❌ Skipping the plan-confirmation step (user wants to see what you'll run)
+- ❌ Running audits in serial when waves allow parallelism
+- ❌ Treating retentionaudit as fix-mode (it's READ-ONLY by design)
+
+## Workflow
+
+```
+User: "/audit-orchestrator security"
+  ↓
+You: parse "security" → secaudit + apiaudit + dataaudit
+You: detect project at Standard level (no "deep/forensic" keyword)
+You: emit plan markdown, ask confirmation
+  ↓
+User: "y"
+  ↓
+You: dispatch 3 audits in parallel via tmux work sessions
+You: monitor verdict.json files appearing under audits/.{name}/
+You: when all 3 done, write audits/SYNTHESIS.md
+You: send Telegram report with aggregate score + per-audit links
+```
+
+## When to invoke alternative skills
+
+- For a SINGLE specific audit → user types `/codeaudit` directly (not via orchestrator)
+- For audit setup / .gitignore / progress dashboard → use `/audit-tracker`
+- For oracle dispatch of audit chain → use `/aisb full`
+
+## Sources
+
+- 17 Quality Arsenal audits in `~/.claude/commands/`
+- Helper docs: `ARSENAL-ORCHESTRATION-PLAYBOOK.md`, `ARSENAL-INTERCONNECTIONS.md`
+- Public mirror: https://github.com/agentik-os/quality-arsenal