arkaos 2.15.0 → 2.16.0

package/arka/skills/fovory/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: arka-fovory
+description: >
+  Fovory ecosystem orchestrator. Supplier-to-Shopify integration engine with custom Laravel codebase
+  (fovory-supplier-sync) AND Shopify store operations. Routes to dev squad for code work and
+  operations/marketing squad for store management. 45 models, 74 actions, 1471 tests, AI module
+  with providers/agents/personas/triggers, AI enrichment pipeline (auto-enrich entities with
+  translations/SEO/GEO/AEO), supplier driver system (Foxway/Realtime/StockFirmati), product import
+  system, variants CRUD, e-commerce settings. Use when user says "fovory", "supplier sync",
+  "shopify", or wants to work on Fovory projects.
+---
+
+# Fovory Ecosystem Orchestrator — ARKA OS
+
+Dedicated orchestrator for the Fovory ecosystem.
+**Dual nature** — custom Laravel codebase (supplier sync engine) + Shopify store operations/marketing.
+
+## Ecosystem Overview
+
+| Project | Type | Stack | Path | Status |
+|---------|------|-------|------|--------|
+| **fovory-supplier-sync** | Supplier Integration Engine | Laravel 13 + Vue 3 + Inertia.js 3 + Nuxt UI 4 | `~/Herd/fovory-supplier-sync` | Active |
+| **Fovory Shopify Store** | E-commerce Store | Shopify (millions of products) | Shopify Admin / MCP | Active |
+
+## Squad (compact)
+
+**Dev Squad (fovory-supplier-sync):** Tech Lead, Backend Dev (Laravel 13/PHP 8.4/Actions), Frontend Dev (Vue 3/Inertia/Nuxt UI 4), AI Specialist (Laravel AI SDK), Security Engineer (OWASP/Sanctum/Fortify), QA (Pest 5 + Playwright).
+
+**Ops & Marketing Squad (Shopify):** Operations Manager (COO), E-Commerce Manager, Product Manager, Marketing Strategist, Content Creator, Ads Specialist, Email Marketing, SEO Specialist, Analytics Specialist, Pricing Strategist.
+
+See `references/integration.md` for full role matrix, tech stack details, and integration mechanics.
+
+## Routing
+
+Auto-discoverable via `/arka do` or `/do`. Synapse routes "fovory", "supplier sync", "shopify store", "shopify operations" here. Direct invocation: `/fovory`.
+
+## Commands
+
+### Development (fovory-supplier-sync)
+
+| Command | Description | Workflow |
+|---------|-------------|----------|
+| `/fovory <description>` | Auto-detect, plan, route | Auto |
+| `/fovory feature <desc>` | New feature (full enterprise flow) | Enterprise |
+| `/fovory forge <desc>` | Forge-plan complex feature | Forge + Enterprise |
+| `/fovory debug <issue>` | Debug with root cause | Focused |
+| `/fovory refactor <scope>` | Refactor + Clean Code audit | Focused |
+| `/fovory review` | Code review of changes | Specialist |
+| `/fovory test` | Run full Pest suite | Specialist |
+| `/fovory plan <desc>` | Plan only (no code) | Planning |
+| `/fovory status` | Branch, tests, commits, store overview | — |
+| `/fovory docs` | Update Obsidian docs | — |
+| `/fovory context` | Full ecosystem context | — |
+
+### Store Operations (Shopify)
+
+| Command | Description |
+|---------|-------------|
+| `/fovory products [import\|translate\|pricing]` | Catalog management |
+| `/fovory marketing [plan\|social\|email\|ads]` | Marketing ops |
+| `/fovory analytics` | Performance dashboard |
+| `/fovory audit` | Full store audit (5 parallel agents) |
+| `/fovory strategy <topic>` | Strategic analysis |
+| `/fovory seo` | SEO audit |
+
+## Workflow Tiers
+
+| Tier | When | Phases |
+|------|------|--------|
+| **Enterprise** | Features, architecture, multi-file | 8 phases (0-7) |
+| **Focused** | Bugs, refactors, store ops | 5 phases (1,2,3,5,7) |
+| **Specialist** | Reviews, tests | 3 phases (4,5,7) |
+
+Full phase-by-phase orchestration (Spec → Forge → Context → Analysis → Plan Approval → Execute → Self-Critique → Quality Gate → Report), `/fovory status` and `/fovory context` scripts, and the plan/report templates live in `references/workflows.md`.
+
+## Quality Gate (NON-NEGOTIABLE)
+
+Every workflow ends in Quality Gate. Marta (CQO) dispatches Eduardo (Copy) and Francisca (Tech/UX) in parallel. Binary APPROVED/REJECTED. REJECTED returns to Execution with specific feedback. See `references/workflows.md` for checklist detail.
+
+## Project Conventions (fovory-supplier-sync) — NON-NEGOTIABLE
+
+UDashboardPanel layout (never raw divs) · UModal forms (never USlideover) · Dropzone uploads (never native inputs) · `bun run build` (never npm) · Always paginate · Pest 5 + Playwright mandatory · `vendor/bin/pint --dirty --format agent` after PHP · Actions in `app/Actions/` · Form Requests for validation · Conventional commits (no Co-Authored-By) · One phase at a time, wait for approval · Spec before code · Browser-verify before done.
+
+## References
+
+- `references/workflows.md` — Full orchestration phases, plan/report templates, status & context commands, Quality Gate checklists.
+- `references/integration.md` — Shopify integration mechanics, supplier pipelines, Laravel codebase specifics, tech stack, modules, marketing channels, analytics, Obsidian output paths.
+
+## Obsidian Output
+
+All documentation: `/Users/andreagroferreira/Documents/Personal/Projects/Fovory/` (see `references/integration.md` for vault tree).

package/arka/skills/fovory/references/integration.md

@@ -0,0 +1,186 @@
+# arka-fovory — integration
+
+Referenced from SKILL.md. Read only when needed.
+
+## Architecture
+
+```
+Suppliers (API + CSV)
+    │
+    ▼
+fovory-supplier-sync (Laravel 13 + Vue 3)
+    ├── Supplier Driver System (Foxway, Realtime, StockFirmati)
+    ├── Product Normalizer (categories, colors, sizes)
+    ├── Deduplicator (EAN-based)
+    ├── AI Enrichment Pipeline (translations, SEO, GEO/AEO)
+    ├── AI System (providers, agents, personas, triggers, budgets)
+    ├── Bulk Import System (Excel, WebSocket progress)
+    ├── Variant/Offer CRUD (cascade status, bulk generation)
+    ├── E-commerce Settings (store config, branding, measurements)
+    └── Shopify Pusher (GraphQL Bulk Operations)
+           │
+           ▼
+    Fovory Shopify Store ──► Customers
+           │
+           ├── Marketing (Social, Ads, Email)
+           ├── Analytics (GA4, Shopify, Meta Pixel)
+           └── Operations (Stock sync, pricing, translations)
+```
+
+## Squad Roles (full matrix)
+
+### Development Squad (fovory-supplier-sync)
+
+| Role | Agent Type | Specialty |
+|------|-----------|-----------|
+| **Tech Lead** | `tech-lead` | Sprint planning, task breakdown, plan presentation, coordination |
+| **Backend Developer** | `backend-dev` | Laravel 13, PHP 8.4, Actions pattern, Eloquent, Form Requests, Horizon |
+| **Frontend Developer** | `frontend-dev` | Vue 3, Inertia.js 3, Nuxt UI 4, TypeScript, Tailwind CSS 4, TipTap, TanStack |
+| **AI Specialist** | `research-analyst` | Laravel AI SDK, Claude/Anthropic, agents/personas/triggers, prompt engineering |
+| **Security Engineer** | `security-eng` | OWASP, Sanctum, Fortify, import validation, API security |
+| **QA Tester** | `qa-eng` | Pest 5 (1471 tests), Playwright E2E, factories, datasets |
+
+### Operations & Marketing Squad (Shopify Store)
+
+| Role | Agent Type | Specialty |
+|------|-----------|-----------|
+| **Operations Manager** | `coo` | Store operations, SOPs, daily tasks, automation |
+| **E-Commerce Manager** | `ecom-director` | Store optimization, conversion, UX audits |
+| **Product Manager** | `commerce-engineer` | Catalog management, CSV bulk ops, translations, stock |
+| **Marketing Strategist** | `strategy-director` | Marketing strategy, campaign planning, market analysis |
+| **Content Creator** | `content-marketer` | Social media posts, Reels scripts, blog articles |
+| **Ads Specialist** | `paid-specialist` | Google Ads, Meta Ads, ad copy, creative strategy |
+| **Email Marketing** | `content-marketer` | Email flows, campaigns, segmentation |
+| **SEO Specialist** | `seo-specialist` | Product SEO, blog SEO, technical SEO |
+| **Analytics Specialist** | `metrics-analyst` | GA4, Shopify analytics, conversion tracking |
+| **Pricing Strategist** | `strategy-director` | Price optimization, competitor pricing, margins |
+
+## Project Conventions (fovory-supplier-sync)
+
+These are NON-NEGOTIABLE when doing code work:
+
+| Convention | Rule |
+|-----------|------|
+| **Layout** | UDashboardPanel with #header/#body slots — never raw divs with max-w |
+| **Forms** | UModal with fieldsets + legends + USeparator — never USlideover |
+| **File uploads** | Drag & drop dropzone pattern — never native file inputs |
+| **Build tool** | `bun run build` — never npm |
+| **Lists/tables** | Always paginate — never load all records |
+| **Testing** | Pest 5 for unit/feature + Playwright for E2E — both mandatory |
+| **PHP formatting** | `vendor/bin/pint --dirty --format agent` after changes |
+| **Business logic** | Action classes in app/Actions/ |
+| **Validation** | Form Request classes |
+| **Commits** | Conventional commits, no Co-Authored-By trailer |
+| **Phases** | Execute one at a time, STOP and wait for user approval |
+| **Spec-driven** | Full interactive spec with user before ANY code |
+| **Browser QA** | Must verify in browser before claiming done |
+
+## Tech Stack Reference
+
+### fovory-supplier-sync
+- **Backend**: PHP 8.4, Laravel 13, Inertia.js 3, Laravel Horizon, Laravel Reverb (WebSocket)
+- **Frontend**: Vue 3.5, TypeScript, Tailwind CSS 4, Nuxt UI 4, TipTap 3, TanStack Table, Unovis charts
+- **Database**: PostgreSQL, Redis, SQLite (dev)
+- **AI**: Laravel AI SDK (`laravel/ai`), Claude/Anthropic providers, agents/personas/triggers
+- **Import**: Maatwebsite Excel, WebSocket progress tracking
+- **Auth**: Laravel Fortify, Laravel Pennant (feature flags)
+- **Testing**: Pest 5, Playwright, Larastan, Rector, Pint
+- **Build**: Bun, Vite
+
+### Codebase Stats (2026-04-11)
+- **45 models** — Products, Variants, Offers, Suppliers, AI (agents/personas/triggers/providers), Enrichment (jobs/batches), Imports, E-commerce Settings
+- **74 actions** — Business logic layer
+- **43 controllers** — HTTP layer
+- **45 Vue pages** — Products, Brands, Categories, Segments, Collections, Attributes, AI, Imports, Settings, Auth
+- **77 migrations** — Full schema
+- **1471 tests** (4159 assertions) — Pest 5
+
+### Key Modules
+- **Supplier Driver System** — Plugin-based architecture (Foxway, RealtimeData, StockFirmati), DriverManager, config registry, dynamic forms
+- **Product Management** — CRUD, variants, offers, images (drag & drop), translations (multi-locale)
+- **AI System** — Providers (OpenRouter, Anthropic, OpenAI), agents (Copywriter, Translator, AttributeMapper), personas, triggers, budgets, competitive analysis
+- **AI Enrichment Pipeline** — Auto-enrich entities with translations, SEO metadata, GEO/AEO content; 4-phase pipeline with smart skip, graceful degradation, WebSocket progress tracking
+- **Import System** — Excel bulk import, template download, WebSocket progress, row-level error reporting
+- **E-commerce Settings** — General info, branding (logo, favicon, OG image with dropzone), measurements (weight/dimension units)
+
+## Shopify Integration
+
+### Via Shopify MCP (`shopify-dev`)
+- Product CRUD (create, read, update, delete)
+- Order management
+- Customer data
+- Inventory/stock management
+- Collection management
+- Discount/promotion management
+
+### CSV Bulk Operations
+For millions of products, use CSV workflows:
+1. Export current catalog from Shopify
+2. Process CSV with transformations (pricing, translations, stock)
+3. Import updated CSV back to Shopify
+4. Verify changes
+
+### Supported Operations
+- **Bulk price updates** (margin calculations, competitor matching, min 35% margin)
+- **Bulk translations** (pt, en, fr, de — via AI agents)
+- **Stock management** (threshold alerts, reorder recommendations, 5% buffer)
+- **Category/tag optimization** (SEO-driven)
+- **Image optimization** (alt texts, descriptions)
+- **Meta descriptions** (SEO-optimized product descriptions)
+
+## Marketing Channels
+
+### Social Media
+- **Instagram** — Posts, Reels, Stories sequences
+- **TikTok** — Short-form video scripts
+- **LinkedIn** — Professional brand content
+- **X/Twitter** — Engagement posts
+- **Pinterest** — Product pins, lookbooks
+
+### Advertising
+- **Google Ads** — Search, Shopping, Display campaigns
+- **Meta Ads** — Facebook/Instagram ads
+- **Google Shopping** — Product feed optimization
+
+### Email Marketing
+- **Welcome sequences** — Onboarding new customers
+- **Cart abandonment** — Recovery flows
+- **Post-purchase** — Upsell, review requests
+- **Win-back** — Re-engagement campaigns
+- **Newsletter** — Regular content
+
+## Analytics & Tracking
+
+| Platform | Purpose |
+|----------|---------|
+| Google Analytics 4 | Traffic, conversions, behavior |
+| Google Ads | Ad performance, ROAS |
+| Shopify Analytics | Revenue, orders, products |
+| Meta Pixel | Facebook/Instagram conversion tracking |
+| Google Search Console | Organic search performance |
+
+## Knowledge Base Integration
+
+Fovory feeds from and contributes to the global knowledge base:
+- **Personas**: Use learned personas (from `/kb learn`) for authentic content voice
+- **Market research**: Feed competitor analysis back into KB
+- **Content patterns**: Learn from successful content for future generation
+- **Price intelligence**: Store pricing data for strategic decisions
+
+## Obsidian Output
+
+All documentation: `/Users/andreagroferreira/Documents/Personal/Projects/Fovory/`
+
+```
+Projects/Fovory/
+├── Home.md                    — Ecosystem overview
+├── Architecture/              — System architecture, data flow
+├── Strategy/                  — Pricing, market, competition
+├── Marketing/                 — Content calendars, campaigns, ads
+│   ├── Social/               — Social media content
+│   ├── Email/                — Email campaigns
+│   └── Ads/                  — Ad campaigns and creatives
+├── Operations/               — SOPs, product management logs
+├── Analytics/                — Performance reports
+└── Decisions/                — Architecture Decision Records
+```

package/arka/skills/fovory/references/workflows.md

@@ -0,0 +1,209 @@
+# arka-fovory — workflows
+
+Referenced from SKILL.md. Read only when needed.
+
+## Orchestration Workflow — Enterprise (Features)
+
+For `/fovory feature` and `/fovory forge`, follow ALL phases in order:
+
+### Phase 0 — Specification (NON-NEGOTIABLE for code work)
+
+Before ANY code, invoke the `arka-spec` skill to create a living spec:
+1. Interactive spec creation with the user (scope, requirements, constraints)
+2. User must APPROVE the spec before proceeding
+3. Spec is the contract — all subsequent phases validate against it
+4. Skip ONLY if user explicitly says "skip spec" or provides a pre-approved spec
+
+### Phase 0.5 — Forge Analysis (for complex requests)
+
+Auto-invoke The Forge (`arka-forge`) when:
+- Request touches **multiple modules** (e.g., supplier driver + enrichment pipeline)
+- Request involves **architecture decisions** (new patterns, data model changes)
+- Request spans **multiple squads** (dev + store ops)
+- User explicitly calls `/fovory forge <description>`
+
+The Forge provides:
+- Complexity scoring across 5 dimensions
+- 3 parallel explorer subagents (Pragmatic, Architectural, Contrarian)
+- Critic synthesis with risk identification
+- Approved ForgePlan before execution begins
+
+Skip when: simple features, single-module changes, or user says "skip forge".
+
+### Phase 1 — Context Loading
+1. Read the ecosystem registry: `~/.claude/skills/arka/knowledge/ecosystems.json`
+2. Read project file: `~/.claude/skills/arka/projects/fovory-supplier-sync/PROJECT.md`
+3. Read CLAUDE.md from `~/Herd/fovory-supplier-sync/CLAUDE.md` (if code work)
+4. Identify whether request is **code** (routes to dev squad) or **store ops** (routes to ops/marketing squad)
+
+### Phase 2 — Analysis & Planning
+
+**Before planning, verify context:**
+- Restate the request to confirm understanding
+- Ask at least 1 clarifying question about scope or intent
+- Challenge at least 1 assumption (devil's advocate)
+- Check memory/knowledge base for prior related work
+
+1. Analyze the request against ecosystem context (and Forge output if available)
+2. Determine which squad roles are needed
+3. Create a detailed execution plan with:
+   - **Request summary**
+   - **Affected area** (supplier-sync codebase / Shopify store / both)
+   - **Squad members involved** (which roles)
+   - **Steps** (numbered, with responsible role)
+   - **Risks/considerations**
+   - **Estimated scope** (files to change, tests to write)
+
+### Phase 3 — Plan Presentation & Approval
+1. Present the plan to the user:
+
+```
+=== Fovory — Execution Plan ===
+
+WORKFLOW: [Enterprise / Focused / Specialist]
+
+REQUEST: [summary]
+
+SPEC: [spec reference or "inline"]
+
+AFFECTED:
+  - [fovory-supplier-sync / Shopify store / both]
+
+SQUAD:
+  - [role] — [responsibility in this task]
+
+STEPS:
+  1. [step] — [role]
+  2. [step] — [role]
+  ...
+
+CONSIDERATIONS:
+  - [risk/note]
+
+================================
+```
+
+2. Ask for user approval:
+   - "Approve plan and proceed?"
+   - Options: "Approve", "Modify", "Cancel"
+
+### Phase 4 — Execution
+1. Only proceed after approval
+2. **Code changes**: Use worktree isolation (NON-NEGOTIABLE)
+3. Each squad role runs as the appropriate agent type
+4. Follow project conventions from CLAUDE.md strictly:
+   - UDashboardPanel layout pattern (never raw divs)
+   - UModal for forms (never USlideover)
+   - Dropzone for file uploads (never native inputs)
+   - `bun run build` (never npm)
+   - Always paginate lists
+   - Pest tests + Playwright E2E mandatory
+5. Run `vendor/bin/pint --dirty --format agent` after PHP changes
+6. Run `php artisan test --compact` to verify
+
+### Phase 5 — Self-Critique & Security Audit
+1. **Self-Critique**: Review own implementation against the spec — identify gaps, edge cases, missed requirements
+2. **Security Audit** (for code work): Check against OWASP Top 10, validate input sanitization, auth/authz, SQL injection, XSS
+3. Fix any issues found before proceeding to Quality Gate
+
+### Phase 6 — Quality Gate (NON-NEGOTIABLE)
+
+**Marta** (CQO) dispatches **Eduardo** and **Francisca** IN PARALLEL:
+
+**Eduardo** (Copy Director) checks:
+- Spelling errors, grammar mistakes
+- Wrong accentuation (critical for pt-PT)
+- AI cliches (no "leverage", "utilize", "streamline", "robust")
+- Tone consistency across all text output
+- Culturally appropriate language
+
+**Francisca** (Tech/UX Director) checks:
+- SOLID principles and Clean Code compliance
+- Test coverage (target: >=80%)
+- OWASP Top 10 security
+- Core Web Vitals and performance
+- UX/WCAG AA accessibility
+- Data integrity and product data accuracy
+- For store ops: pricing accuracy, translations, images, inventory sync
+
+**Verdict:** APPROVED or REJECTED. Binary, no caveats, no exceptions.
+- APPROVED → proceed to Documentation phase
+- REJECTED → return to Execution phase with specific feedback, fix, re-submit
+
+### Phase 7 — Documentation & Report
+1. Update Obsidian documentation if significant
+2. Present execution report:
+
+```
+=== Fovory — Execution Report ===
+
+WORKFLOW: [Enterprise / Focused / Specialist]
+
+COMPLETED:
+  - [what was done]
+
+FILES CHANGED:
+  - [files]
+
+TESTS:
+  - [test results — X passed / Y assertions]
+
+QUALITY GATE:
+  - Eduardo: [APPROVED/REJECTED — notes]
+  - Francisca: [APPROVED/REJECTED — notes]
+
+DOCS UPDATED:
+  - [obsidian pages updated]
+
+=================================
+```
+
+## Orchestration Workflow — Focused (Bugs, Refactors, Store Ops)
+
+For `/fovory debug`, `/fovory refactor`, and store operation commands:
+- Skip Phase 0 (Spec) and Phase 0.5 (Forge)
+- Follow Phases: **1 → 2 → 3 → 4 → 5 → 6 → 7**
+- Phase 5 (Self-Critique) focuses on root cause validation (bugs) or data accuracy (store ops)
+
+## Orchestration Workflow — Specialist (Reviews, Tests)
+
+For `/fovory review`, `/fovory test`:
+- Skip Phases 0, 0.5, 1, 2, 3
+- Follow Phases: **4 → 6 → 7** (Execute → Quality Gate → Report)
+- Direct execution with quality validation
+
+## /fovory status
+
+Check the status of the ecosystem:
+
+```bash
+# fovory-supplier-sync
+cd ~/Herd/fovory-supplier-sync
+git status
+git log --oneline -5
+git branch --show-current
+php artisan test --compact 2>&1 | tail -3
+```
+
+Present as:
+
+```
+=== Fovory — Ecosystem Status ===
+
+CODE: fovory-supplier-sync (Laravel 13 + Vue 3)
+  Branch: [branch]
+  Last commit: [hash] — [message] ([date])
+  Status: [clean/uncommitted changes]
+  Tests: [X passed / Y assertions]
+
+STORE: Fovory Shopify
+  [Shopify MCP status if available]
+
+==================================
+```
+
+## /fovory context
+
+Show full ecosystem context:
+1. Read all project files and CLAUDE.md
+2. Present architecture, tech stack, modules, conventions, current state

package/arka/skills/platform-arka/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: arka-platform-arka
+description: >
+  ArkaOS platform ecosystem orchestrator. Self-managing product development for ArkaOS —
+  the core WizardingCode product. Full-stack product team: Python core engine, Node.js
+  installer/CLI, React dashboard, skills, agents, departments. Manages features, fixes,
+  releases (semi-auto with confirmation gate), test suite (542+ pytest), self-auditing,
+  and auto-evolution (detects gaps, proposes and implements improvements).
+  Reports to /wiz (WizardingCode Internal) for strategic alignment.
+  Use when user says "platform-arka", "arkaos dev", "arkaos feature", "arkaos release",
+  "arkaos audit", "arkaos evolve", "platform", or wants to develop/improve ArkaOS itself.
+---
+
+# ArkaOS Platform — Product Development Ecosystem
+
+Self-managing product development orchestrator for ArkaOS. **The system that evolves itself.**
+
+## Project
+
+| Property | Value |
+|----------|-------|
+| **Product** | ArkaOS |
+| **Company** | WizardingCode |
+| **Path** | `/Users/andreagroferreira/AIProjects/arka-os` |
+| **Stack** | Python (core) + Node.js (installer/CLI) + React (dashboard) |
+| **Reports to** | `/wiz` (WizardingCode Internal) |
+| **Version file** | `VERSION` (also `package.json`, `pyproject.toml`) |
+| **Tests** | `pytest` (542+ tests in `tests/python/`) |
+
+## Architecture
+
+```
+core/ (Python: Synapse, workflows, agents, governance, runtime)
+installer/ (Node.js CLI + adapters) · scripts/ (React dashboard + FastAPI)
+departments/ (17 depts: agents, skills, workflows) · config/ · knowledge/
+tests/python/ (542+ pytest)
+```
+
+## Squad — The Platform Team
+
+| Role | Agent Type | Responsibility |
+|------|-----------|----------------|
+| **Product Owner** | `strategy-director` | Roadmap, prioritization, OKRs, reports to `/wiz` |
+| **Core Engineer** | `backend-dev` | Python core — Synapse, workflows, agents, governance |
+| **CLI Engineer** | `backend-dev` | Node.js installer, CLI tools, bash hooks |
+| **Dashboard Engineer** | `frontend-dev` | React dashboard, FastAPI endpoints, WebSocket |
+| **Skill Architect** | `architect` | Skill design, agent YAML, department structure |
+| **DevOps** | `devops-eng` | npm publish, GitHub releases, CI/CD, versioning |
+| **QA Engineer** | `qa-eng` | pytest suite, integration tests, regression |
+| **Security Engineer** | `security-eng` | Dependency audit, OWASP, installer security |
+| **Platform Analyst** | `research-analyst` | Self-analysis, gap detection, evolution proposals |
+
+## Commands
+
+### Standard Product Commands
+
+| Command | Description |
+|---------|-------------|
+| `/platform-arka` | General — describe what you need, orchestrator routes |
+| `/platform-arka status` | Project status (version, coverage, issues, releases) |
+| `/platform-arka feature <desc>` | Plan and implement a new feature |
+| `/platform-arka fix <desc>` | Debug and fix an issue |
+| `/platform-arka test` | Run full pytest suite + report |
+| `/platform-arka review` | Code review of recent changes |
+| `/platform-arka docs` | Update documentation (CLAUDE.md, CONTRIBUTING, Obsidian) |
+
+### Release Pipeline
+
+| Command | Description |
+|---------|-------------|
+| `/platform-arka release <type>` | Semi-auto release: bump, changelog, commit. Pauses before push + npm publish + GitHub release |
+| `/platform-arka release status` | Check latest release, npm version, GitHub tags |
+
+### Auto-Evolution Commands
+
+| Command | Description |
+|---------|-------------|
+| `/platform-arka audit` | Self-analysis: code quality, test gaps, missing skills, agents without DNA, dead code, CLAUDE.md accuracy |
+| `/platform-arka evolve` | Propose improvements from audit — with approval, implements |
+| `/platform-arka roadmap` | View/update roadmap, synced with `/wiz` priorities |
+| `/platform-arka metrics` | Coverage, agent count, skill count, department completeness, version history |
+
+### Skill & Agent Management
+
+| Command | Description |
+|---------|-------------|
+| `/platform-arka skill create <name>` | Scaffold a new skill (SKILL.md + registration) |
+| `/platform-arka skill list` | List all skills with status |
+| `/platform-arka agent create <name>` | Create new agent YAML with behavioral DNA |
+| `/platform-arka agent validate` | Validate all agent YAMLs (4-framework consistency) |
+| `/platform-arka department <name>` | Department health check (agents, skills, workflows) |
+
+## Orchestration
+
+The squad executes every request through a common arc: context loading → planning → user approval → execution (branch/worktree isolation where applicable) → Quality Gate (Marta/Eduardo/Francisca, mandatory) → Obsidian documentation. Releases additionally pause at a confirmation gate before publish. Evolve and audit flows use the Platform Analyst to scan departments, agents, skills, test coverage, and code quality, then propose ranked improvements.
+
+**See `references/workflows.md` for the full step-by-step flows** (Standard, Release, Audit, Evolve, Status, Metrics, Skill Create, Agent Create).
+
+## Branch Strategy
+
+| Scenario | Branch Pattern | Isolation |
+|----------|---------------|-----------|
+| Features | `feature/<desc>` | Worktree |
+| Evolution improvements | `evolve/<desc>` | Worktree |
+| Hotfixes, simple patches | Direct on `master` | None |
+| Releases | From `master` | None (bump + tag + publish) |
+
+## /wiz Integration
+
+- ArkaOS appears in `/wiz projects` and `/wiz status` as an active internal project
+- `/wiz` sets strategic priorities that `/platform-arka roadmap` reflects
+- Revenue (ARKA OS Pro) tracked via `/wiz finance`; roadmap syncs against `/wiz` OKRs
+
+## Obsidian Output
+
+All documentation under `/Users/andreagroferreira/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/`:
+`Roadmap.md`, `Releases/vX.Y.Z.md`, `Audits/YYYY-MM-DD.md`, `Evolution Log.md`, `Metrics.md`.
+
+## References
+
+- `references/workflows.md` — Full orchestration flows (Standard, Release, Audit, Evolve, Status, Metrics, Skill Create, Agent Create)