arkaos 2.15.0 → 2.16.0

package/departments/dev/skills/onboard/references/stack-detection.md

@@ -0,0 +1,83 @@
+# arka-onboard — Stack Detection
+
+Referenced from SKILL.md. Read only when needed.
+
+## Step 1: Validate Path
+
+```python
+python3 "$ARKA_OS/../arka-onboard/scripts/detect-stack.py" "<path>" --json
+```
+
+If the path doesn't exist, resolve relative to `$HOME` or common project directories (`~/Herd/`, `~/Projects/`, `~/Code/`).
+
+Check if already onboarded: look for `projects/<name>/PROJECT.md` in `$ARKA_OS`.
+
+## Step 2: Auto-Detect Stack
+
+Run the bundled detection script:
+
+```bash
+python3 "$(dirname "$0")/scripts/detect-stack.py" "<resolved-path>" --json
+```
+
+This returns a JSON report with:
+- **Framework** — Laravel, Nuxt, Vue, React, Next.js, Django, FastAPI, etc.
+- **Language** — PHP, TypeScript, Python, etc.
+- **Stack** — full list of detected technologies
+- **Database** — PostgreSQL, MySQL, SQLite, Supabase
+- **Cache/Queue** — Redis, Horizon
+- **Auth** — Sanctum, Passport, NextAuth, Supabase Auth
+- **Payments** — Stripe, Paddle
+- **CSS** — Tailwind, Sass, Nuxt UI, shadcn/ui
+- **Testing** — Pest, PHPUnit, Vitest, Jest, Playwright
+- **Architecture** — monolith, api-only, monorepo, frontend-spa
+- **Patterns** — Services, Repositories, Actions, DTOs
+- **Conventions** — TypeScript, ESLint, Prettier, PHPStan, Docker
+- **Metrics** — models, controllers, migrations, components, pages, tests
+- **MCP Profile** — recommended profile (laravel/nuxt/vue/react/nextjs/full-stack/base)
+
+If the script is not available, detect manually by reading:
+- `composer.json` — PHP/Laravel dependencies
+- `package.json` — Node.js/frontend dependencies
+- `nuxt.config.ts` / `next.config.ts` — framework config
+- `.env.example` or `.env` — database, cache, queue, payment keys
+- `docker-compose.yml` — infrastructure setup
+
+## Step 3: Architecture Analysis
+
+Glob the project directory to understand its structure:
+
+```
+# Laravel
+app/Models/*.php         → count models
+app/Http/Controllers/    → count controllers
+database/migrations/     → count migrations
+routes/*.php             → count route files
+app/Services/            → Services pattern?
+app/Repositories/        → Repository pattern?
+tests/                   → count tests
+
+# Frontend
+components/**/*.vue|tsx  → count components
+pages/**/*.vue|tsx       → count pages
+composables/             → composables pattern?
+stores/                  → state management?
+```
+
+Determine:
+- **Monolith** — backend + frontend views in one repo
+- **API-only** — backend without frontend views
+- **Monorepo** — `api/` + `frontend/` or `apps/` + `packages/`
+- **Frontend SPA** — no backend, just frontend
+
+## Step 4: Git Analysis
+
+Read-only git commands to understand project history:
+
+```bash
+git -C "<path>" remote -v                    # remotes
+git -C "<path>" branch -a                    # branches
+git -C "<path>" log --oneline -10            # recent commits
+git -C "<path>" shortlog -sn --no-merges | head -5  # top contributors
+git -C "<path>" rev-list --count HEAD        # total commits
+```

package/departments/dev/workflows/debug.yaml

@@ -42,6 +42,7 @@ phases:
 
   - id: quality-gate
     name: Quality Gate
+    model_override: opus
     description: Review fix quality
     agents:
       - agent_id: cqo-marta

package/departments/dev/workflows/feature.yaml

@@ -11,6 +11,7 @@ quality_gate_required: true
 phases:
   - id: spec
     name: Specification
+    model_override: opus
     description: Create or validate feature specification
     agents:
       - agent_id: tech-lead-paulo
@@ -36,6 +37,7 @@ phases:
 
   - id: architecture
     name: Architecture
+    model_override: opus
     description: Design system architecture and write ADR
     agents:
       - agent_id: architect-gabriel
@@ -99,6 +101,7 @@ phases:
 
   - id: quality-gate
     name: Quality Gate
+    model_override: opus
     description: Mandatory review by CQO, Copy Director, and Tech Director
     agents:
       - agent_id: cqo-marta

package/departments/dev/workflows/refactor.yaml

@@ -43,6 +43,7 @@ phases:
 
   - id: quality-gate
     name: Quality Gate
+    model_override: opus
     description: Review refactored code
     agents:
       - agent_id: cqo-marta

package/departments/ecom/SKILL.md

@@ -37,3 +37,16 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | **David** (Engineer) | 2 | C+D | Shopify, headless, checkout, APIs |
 
 ## Frameworks: ResearchXL (CXL), RFM (Sanocki), MACH Architecture, Baymard UX Guidelines, E-Commerce Metrics Stack, Subscription Models, Marketplace Flywheel
+
+## Model Selection
+
+When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
+
+- Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
+- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Default to `sonnet` if the agent YAML has no `model` field
+- Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
+
+Example Task tool call:
+
+    Task(description="...", subagent_type="general-purpose", model="sonnet", prompt="...")

package/departments/ecom/agents/commerce-engineer.yaml

@@ -3,6 +3,7 @@ name: David
 role: Commerce Engineer
 department: ecom
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/ecom/agents/cro-specialist.yaml

@@ -3,6 +3,7 @@ name: Alice
 role: CRO Specialist
 department: ecom
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/ecom/agents/ecom-director.yaml

@@ -3,6 +3,7 @@ name: Ricardo
 role: E-Commerce Director
 department: ecom
 tier: 1
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/ecom/agents/retention-manager.yaml

@@ -3,6 +3,7 @@ name: Catarina
 role: Retention & Email Manager
 department: ecom
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/ecom/skills/ecommerce/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: arka-ecommerce
+description: >
+  E-commerce department. Full store audits with 5 parallel agents (UX, SEO, performance,
+  content, conversion), product listing optimization, pricing strategy analysis, store launch
+  plans, e-commerce ad campaigns, competitor analysis, e-commerce SEO audits, automated email
+  flows (cart abandonment, post-purchase, win-back), and store performance reports. Integrates
+  with Shopify MCP for direct product/order/customer management. All output saved to Obsidian.
+  Use when user says "ecom", "store", "product", "shop", "shopify", "ecommerce", "e-commerce",
+  "sales", "conversion", "pricing", "catalog", "inventory", "cart", "checkout", "listing",
+  or any online store task.
+---
+
+# E-commerce Department — ARKA OS
+
+Store management, product optimization, and e-commerce growth. All output saved to Obsidian (`WizardingCode/Ecommerce/`) with wikilinks and kebab-case tags.
+
+## Squad (compact)
+
+- **Ricardo** — Lead (brief, planning, execution, self-critique, delivery)
+- **Tomas** — Strategy challenge (Phase 1)
+- **Helena (CFO)** — Financial supervision (Phase 1 + 5)
+- **Marta (CQO)** — Quality Gate orchestrator (Phase 6) — absolute veto
+- **Eduardo + Francisca** — Copy + technical review under Marta
+
+## Universal Workflow (7-Phase — NON-NEGOTIABLE)
+
+Phase 0 BRIEF → Phase 1 CHALLENGE/RESEARCH → Phase 2 PLANNING → Phase 3 EXECUTION → Phase 4 SELF-CRITIQUE → Phase 5 SUPERVISION (Helena) → Phase 6 QUALITY GATE (Marta) → Phase 7 DELIVERY. Every phase transition is announced. No output reaches the user without Marta's APPROVED.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ecom audit <url>` | Full store audit (5 parallel agents) |
+| `/ecom product <description>` | Create optimized product listing |
+| `/ecom pricing <product>` | Pricing strategy analysis |
+| `/ecom launch <store>` | New store launch plan |
+| `/ecom ads <product>` | E-commerce ad campaigns |
+| `/ecom competitors <url>` | Competitive e-commerce analysis |
+| `/ecom seo <url>` | E-commerce SEO audit |
+| `/ecom email <type>` | Email flows (cart, post-purchase, win-back) |
+| `/ecom report <store>` | Store performance report |
+
+## Obsidian Output
+
+| Content | Vault Path |
+|---------|-----------|
+| Store audits | `WizardingCode/Ecommerce/Audits/<date> <store>.md` |
+| Product analyses | `WizardingCode/Ecommerce/Products/<name>.md` |
+| Competitor research | `WizardingCode/Ecommerce/Competitors/<date> <name>.md` |
+| Launch plans | `WizardingCode/Ecommerce/Launches/<store>.md` |
+| Performance reports | `WizardingCode/Ecommerce/Reports/<date> <store>.md` |
+
+## MCP Integration
+
+Shopify MCP (when available): products, orders, customers, discounts, shop details.
+
+## References
+
+Load only when executing the relevant workflow:
+
+- `references/audit-flow.md` — 5-parallel-agents audit (UX, SEO, performance, content, conversion), synthesis, Obsidian template, report format
+- `references/playbooks.md` — Product listing optimization, pricing strategy (competitor + margin + psychological), RFM, marketplace operations
+
+---
+*All output: `WizardingCode/Ecommerce/` — Part of the [[WizardingCode MOC]]*

package/departments/ecom/skills/ecommerce/references/audit-flow.md

@@ -0,0 +1,109 @@
+# arka-ecommerce — Audit Flow (5 Parallel Agents)
+
+Referenced from SKILL.md. Read only when needed.
+
+## /ecom audit <url>
+
+### Step 1: Fetch Store Data
+- Use WebFetch to crawl the store URL
+- Capture homepage, key product pages, cart, checkout flow
+
+### Step 2: Run 5 Parallel Audit Agents
+
+Launch these agents simultaneously:
+
+**Agent 1: UX Auditor**
+- Navigation and information architecture
+- Mobile responsiveness
+- Page load perception
+- Cart and checkout friction
+- Search and filtering usability
+
+**Agent 2: SEO Auditor**
+- Title tags, meta descriptions, heading structure
+- Product page SEO (schema markup, alt text, URLs)
+- Internal linking and site structure
+- Collection/category page optimization
+- Technical SEO (canonical URLs, sitemap, robots.txt)
+
+**Agent 3: Performance Auditor**
+- Page load speed indicators
+- Image optimization assessment
+- Third-party script overhead
+- Core Web Vitals estimation
+- Mobile performance
+
+**Agent 4: Content Auditor**
+- Product descriptions (quality, length, persuasion)
+- Product photography assessment
+- Trust signals (reviews, badges, guarantees)
+- Brand consistency across pages
+- Copy effectiveness (headlines, CTAs)
+
+**Agent 5: Conversion Auditor**
+- Call-to-action clarity and placement
+- Social proof visibility
+- Urgency/scarcity elements
+- Upsell and cross-sell opportunities
+- Abandoned cart recovery signals
+- Email capture strategy
+
+### Step 3: Synthesize Results
+- Combine all 5 agent reports
+- Prioritize findings by impact (high/medium/low)
+- Create actionable recommendations with estimated effort
+
+### Step 4: Save to Obsidian
+
+**File:** `WizardingCode/Ecommerce/Audits/<YYYY-MM-DD> <store>.md`
+```markdown
+---
+type: audit
+department: ecommerce
+title: "<store> — E-commerce Audit"
+url: "<url>"
+date_created: <YYYY-MM-DD>
+tags:
+  - "audit"
+  - "ecommerce"
+---
+
+# <store> — E-commerce Audit
+
+## Executive Summary
+[Top 3-5 findings and overall score]
+
+## UX Analysis
+[Agent 1 findings]
+
+## SEO Analysis
+[Agent 2 findings]
+
+## Performance Analysis
+[Agent 3 findings]
+
+## Content Analysis
+[Agent 4 findings]
+
+## Conversion Analysis
+[Agent 5 findings]
+
+## Priority Actions
+| # | Action | Impact | Effort | Category |
+|---|--------|--------|--------|----------|
+| 1 | [action] | High | [effort] | [category] |
+
+---
+*Part of the [[WizardingCode MOC]]*
+```
+
+### Step 5: Report
+```
+═══ ARKA ECOM — Store Audit Complete ═══
+Store:       <store>
+URL:         <url>
+Issues:      <count> (High: X, Medium: Y, Low: Z)
+Top action:  <highest impact recommendation>
+Obsidian:    WizardingCode/Ecommerce/Audits/<date> <store>.md
+═════════════════════════════════════════
+```

package/departments/ecom/skills/ecommerce/references/playbooks.md

@@ -0,0 +1,141 @@
+# arka-ecommerce — Playbooks (Product, Pricing, RFM, Marketplace)
+
+Referenced from SKILL.md. Read only when needed.
+
+## /ecom product <description>
+
+**Step 1: Research**
+- Understand the product from the description
+- If URL provided, use WebFetch to analyze the current listing
+- If Shopify MCP available, pull existing product data
+
+**Step 2: Optimize Product Listing**
+- Title: SEO-optimized, keyword-rich, clear benefit
+- Description: Problem → Solution → Benefits → Features → CTA
+- Bullet points: Feature → Benefit format
+- SEO tags: Primary keyword, long-tail variants, related terms
+- Meta description: 155 chars, keyword-included, click-worthy
+
+**Step 3: Generate Variants**
+- 3 title options (SEO vs. emotional vs. benefit-led)
+- Short description (50 words) and long description (200+ words)
+- Suggested collections/categories
+- Cross-sell and upsell suggestions
+
+**Step 4: Save to Obsidian**
+
+**File:** `WizardingCode/Ecommerce/Products/<name>.md`
+```markdown
+---
+type: product
+department: ecommerce
+title: "<product name>"
+date_created: <YYYY-MM-DD>
+tags:
+  - "product"
+  - "ecommerce"
+---
+
+# <product name>
+
+## Optimized Listing
+### Title Options
+1. [SEO-focused]
+2. [Emotion-focused]
+3. [Benefit-focused]
+
+### Description
+[Optimized product description]
+
+### Bullet Points
+- [Feature → Benefit]
+
+### SEO
+- Primary keyword: [keyword]
+- Tags: [list]
+- Meta description: [155 chars]
+
+### Upsell/Cross-sell
+- [Suggestions]
+
+---
+*Part of the [[WizardingCode MOC]]*
+```
+
+**Step 5: Apply via Shopify MCP**
+- If Shopify MCP is available and user confirms, push the optimized listing directly
+
+## /ecom pricing <product>
+
+**Step 1: Gather Product Data**
+- Current price (if exists)
+- Cost of goods / margin
+- Product category and positioning
+
+**Step 2: Competitor Analysis**
+- Use WebFetch to research 3-5 competitor prices for similar products
+- Map price range: budget → mid-range → premium
+
+**Step 3: Pricing Strategy**
+- Calculate margin at different price points
+- Apply psychological pricing (charm pricing, anchoring, decoy)
+- Consider bundling opportunities
+- Evaluate penetration vs. skimming strategy
+
+**Step 4: Generate Recommendation**
+
+**File:** `WizardingCode/Ecommerce/Products/<product>-pricing.md`
+```markdown
+---
+type: pricing-analysis
+department: ecommerce
+title: "<product> — Pricing Strategy"
+date_created: <YYYY-MM-DD>
+tags:
+  - "pricing"
+  - "ecommerce"
+---
+
+# <product> — Pricing Strategy
+
+## Competitor Landscape
+| Competitor | Product | Price | Positioning |
+|-----------|---------|-------|-------------|
+| [name] | [product] | [price] | [budget/mid/premium] |
+
+## Margin Analysis
+| Price Point | Margin | Margin % | Notes |
+|------------|--------|----------|-------|
+| [price] | [margin] | [%] | [note] |
+
+## Recommendation
+- **Recommended price:** [price]
+- **Strategy:** [penetration/skimming/competitive]
+- **Rationale:** [why this price wins]
+
+## Psychological Pricing
+- [Techniques to apply]
+
+## Bundle Opportunities
+- [Bundle suggestions with margin impact]
+
+---
+*Part of the [[WizardingCode MOC]]*
+```
+
+## RFM Segmentation
+
+Recency, Frequency, Monetary analysis. Identify Champions, Loyal Customers, At-Risk, Hibernating, Lost. Map segments to lifecycle email flows and win-back offers.
+
+## Marketplace Operations
+
+Seller onboarding, commission models, quality control, dispute resolution, catalog governance, listing quality scores, marketplace-specific SEO (Amazon A9, eBay Cassini).
+
+## MCP Integration
+
+Shopify MCP when available:
+- Product management (get-products, get-collections)
+- Order management (get-orders, get-order)
+- Customer management (get-customers, tag-customer)
+- Discount creation (create-discount)
+- Store info (get-shop-details)

package/departments/ecom/workflows/product-page.yaml

@@ -33,6 +33,7 @@ phases:
 
   - id: quality-gate
     name: Quality Gate
+    model_override: opus
     description: Review recommendations
     agents:
       - agent_id: cqo-marta

package/departments/finance/SKILL.md

@@ -35,3 +35,16 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | **Rui** | 2 | D+I | Fundraising, term sheets, cap table, M&A |
 
 ## Frameworks: 3-Statement Model, DCF (Damodaran), Unit Economics (SaaS), COSO ERM, FP&A Cycle, VC Framework (Feld), Scenario Analysis, Monte Carlo
+
+## Model Selection
+
+When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
+
+- Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
+- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Default to `sonnet` if the agent YAML has no `model` field
+- Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
+
+Example Task tool call:
+
+    Task(description="...", subagent_type="general-purpose", model="sonnet", prompt="...")

package/departments/finance/agents/cfo.yaml

@@ -3,6 +3,7 @@ name: Helena
 role: Chief Financial Officer
 department: finance
 tier: 0
+model: opus
 
 behavioral_dna:
   disc:

package/departments/finance/agents/financial-analyst.yaml

@@ -3,6 +3,7 @@ name: Leonor
 role: Financial Analyst
 department: finance
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/finance/agents/investment-strategist.yaml

@@ -3,6 +3,7 @@ name: Rui
 role: Investment & Fundraising Strategist
 department: finance
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/finance/workflows/cashflow.yaml

@@ -25,6 +25,7 @@ phases:
     description: User reviews assumptions
 - id: quality-gate
   name: Quality Gate
+  model_override: opus
   agents:
   - agent_id: cqo-marta
     role: Orchestrate

package/departments/finance/workflows/model.yaml

@@ -54,6 +54,7 @@ phases:
 
   - id: quality-gate
     name: Quality Gate
+    model_override: opus
     description: Validate model accuracy and assumptions
     agents:
       - agent_id: cqo-marta

package/departments/kb/SKILL.md

@@ -36,3 +36,16 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | **Helena C.** | 2 | S+C | Vault maintenance, Zettelkasten, MOCs, linking |
 
 ## Frameworks: Zettelkasten (Luhmann), BASB/CODE/PARA (Forte), SECI Model (Nonaka/Takeuchi), LYT/MOCs (Milo), Progressive Summarization, CRAAP Test, Research Methodology
+
+## Model Selection
+
+When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
+
+- Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
+- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Default to `sonnet` if the agent YAML has no `model` field
+- Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
+
+Example Task tool call:
+
+    Task(description="...", subagent_type="general-purpose", model="sonnet", prompt="...")

package/departments/kb/agents/data-collector.yaml

@@ -3,6 +3,7 @@ name: Tomas Jr
 role: Data Collector
 department: kb
 tier: 3
+model: haiku
 
 behavioral_dna:
   disc:

package/departments/kb/agents/knowledge-curator.yaml

@@ -3,6 +3,7 @@ name: Helena C.
 role: Knowledge Curator
 department: kb
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/kb/agents/knowledge-director.yaml

@@ -3,6 +3,7 @@ name: Clara
 role: Knowledge Director
 department: kb
 tier: 1
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/kb/agents/research-analyst.yaml

@@ -3,6 +3,7 @@ name: Francisco
 role: Research Analyst
 department: kb
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc: