arkaos 2.0.0 → 2.0.1

package/README.md

@@ -1,22 +1,25 @@
 # ArkaOS
 
-**The Operating System for AI Agent Teams.** 56 specialized agents across 16 departments, backed by 116 enterprise frameworks. One install. Full company capability.
+**The Operating System for AI Agent Teams.** 62 agents across 17 departments, 250+ skills backed by 116 enterprise frameworks, 8 Python CLI tools. One install.
 
 ```
 npx arkaos install
 ```
 
+[![Tests](https://github.com/andreagroferreira/arka-os/actions/workflows/test.yml/badge.svg)](https://github.com/andreagroferreira/arka-os/actions) [![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 ## What ArkaOS Does
 
-ArkaOS orchestrates AI agents that cover every business function. Not just code. Marketing, brand, finance, strategy, sales, operations, product management, e-commerce, communities, content, and more.
+ArkaOS orchestrates AI agents that cover every business function. Not just code. Marketing, brand, finance, strategy, sales, operations, compliance, product management, e-commerce, communities, content, and more.
 
-Each agent has a defined role, personality, expertise, and authority level. They work in squads, follow structured workflows, and every output passes through a mandatory Quality Gate before reaching you.
+Each agent has a defined role, personality, expertise, and authority level. They work in squads, follow YAML workflows, and every output passes through a mandatory Quality Gate.
 
 ```
 You: "validate my saas idea for a scheduling tool"
+
 ArkaOS: → Routes to SaaS department
         → Tiago (SaaS Strategist) leads validation workflow
-        → Market sizing, competitor analysis, business model, pricing, MVP scope
+        → Market sizing, competitor analysis, business model, pricing
         → Financial viability check by Leonor (Financial Analyst)
         → Quality Gate: Marta, Eduardo, Francisca review
         → Delivers: validated report with go/no-go recommendation
@@ -25,108 +28,127 @@ ArkaOS: → Routes to SaaS department
 ## Install
 
 ```bash
-# Auto-detects your AI runtime
-npx arkaos install
-
-# Or specify the runtime
+npx arkaos install              # auto-detects runtime
 npx arkaos install --runtime claude-code
 npx arkaos install --runtime codex
 npx arkaos install --runtime gemini
 npx arkaos install --runtime cursor
 ```
 
-Requires: Node.js 18+ and Python 3.11+
-
-## 16 Departments, 56 Agents
-
-| Department | Prefix | Agents | What It Does |
-|-----------|--------|--------|-------------|
-| Development | `/dev` | 9 | Features, APIs, architecture, security, CI/CD, testing |
-| Marketing | `/mkt` | 4 | SEO, paid ads, content, email, growth loops |
-| Brand & Design | `/brand` | 4 | Brand identity, UX/UI, design systems, naming |
-| Finance | `/fin` | 3 | Financial models, valuation, fundraising, unit economics |
-| Strategy | `/strat` | 3 | Five Forces, Blue Ocean, BMC, competitive intelligence |
-| E-Commerce | `/ecom` | 4 | Store optimization, CRO, RFM, pricing, marketplace |
-| Knowledge | `/kb` | 3 | Research, Zettelkasten, personas, Obsidian curation |
-| Operations | `/ops` | 2 | Automation (n8n, Zapier), SOPs, bottleneck analysis |
-| Project Mgmt | `/pm` | 3 | Scrum, Kanban, Shape Up, discovery, roadmaps |
-| SaaS | `/saas` | 3 | Validation, metrics, PLG, pricing, customer success |
-| Landing Pages | `/landing` | 4 | Sales copy, funnels, offers, launches, affiliates |
-| Content | `/content` | 4 | Viral design, hooks, scripts, repurposing (1 to 30+) |
-| Communities | `/community` | 2 | Telegram, Discord, Skool groups, membership monetization |
-| Sales | `/sales` | 2 | Pipeline, proposals, SPIN selling, negotiation |
-| Leadership | `/lead` | 2 | Team health, hiring, feedback, OKRs, culture |
-| Organization | `/org` | 1 | Org design, team topologies, scaling operations |
-| **Quality Gate** | (auto) | 3 | Mandatory review on every workflow. Veto power. |
+Requires Node.js 18+ and Python 3.11+.
+
+**Upgrading from v1?** Run `npx arkaos migrate`
+
+## 17 Departments, 62 Agents
+
+| Department | Prefix | Agents | Skills | What It Does |
+|-----------|--------|--------|--------|-------------|
+| Development | `/dev` | 9 | 41 | Features, APIs, architecture, security, CI/CD, RAG, agents |
+| Marketing | `/mkt` | 4 | 14 | SEO, paid ads, email, growth loops, programmatic SEO |
+| Brand & Design | `/brand` | 4 | 12 | Brand identity, UX/UI, design systems, naming |
+| Finance | `/fin` | 3 | 8 | DCF valuation, unit economics, CISO advisory |
+| Strategy | `/strat` | 3 | 9 | Five Forces, Blue Ocean, BMC, CTO/board advisory |
+| E-Commerce | `/ecom` | 4 | 12 | Store optimization, CRO, RFM, pricing |
+| Knowledge | `/kb` | 3 | 12 | Research, Zettelkasten, personas, Obsidian |
+| Operations | `/ops` | 2 | 15 | Automation, SOPs, GDPR, ISO 27001, SOC 2, risk |
+| Project Mgmt | `/pm` | 3 | 13 | Scrum, Shape Up, discovery, agile PO |
+| SaaS | `/saas` | 3 | 15 | Validation, metrics, PLG, scaffolding |
+| Landing Pages | `/landing` | 4 | 15 | Sales copy, funnels, offers, page generation |
+| Content | `/content` | 4 | 14 | Viral design, hooks, scripts, repurposing |
+| Communities | `/community` | 2 | 14 | Groups, membership, gamification |
+| Sales | `/sales` | 2 | 10 | Pipeline, SPIN selling, negotiation |
+| Leadership | `/lead` | 2 | 10 | Team health, OKRs, culture, hiring |
+| Organization | `/org` | 1 | 10 | Org design, team topologies |
+| **Quality Gate** | (auto) | 3 | — | Mandatory on every workflow. Veto power. |
 
 ## How It Works
 
 **Just describe what you need.** ArkaOS routes it to the right squad.
 
 ```
-"add user authentication"     → /dev feature
-"create a brand for my app"   → /brand identity
-"plan our Q3 budget"          → /fin budget
-"design a sales funnel"       → /landing funnel
-"grow my Discord community"   → /community grow
-"write viral hooks for TikTok"→ /content hook
+"add user authentication"      → /dev feature
+"create a brand for my app"    → /brand identity
+"plan our Q3 budget"           → /fin budget
+"design a sales funnel"        → /landing funnel
+"are we GDPR compliant?"       → /ops gdpr-compliance
+"score these headlines"        → python scripts/tools/headline_scorer.py
 ```
 
-Or use explicit commands: `/dev feature "user auth"`, `/saas validate "scheduling tool"`, `/strat blue-ocean "AI tools market"`
+Or use explicit commands: `/dev feature "user auth"`, `/saas validate "scheduling tool"`
+
+## Python CLI Tools
+
+8 stdlib-only tools for quantitative analysis. No dependencies.
+
+```bash
+python scripts/tools/headline_scorer.py "10x Your Revenue" --json
+python scripts/tools/seo_checker.py page.html --json
+python scripts/tools/rice_prioritizer.py features.json --json
+python scripts/tools/dcf_calculator.py --revenue 1000000 --growth 20 --json
+python scripts/tools/tech_debt_analyzer.py src/ --json
+python scripts/tools/saas_metrics.py --new-mrr 50000 --json
+python scripts/tools/brand_voice_analyzer.py content.txt --json
+python scripts/tools/okr_cascade.py growth --json
+```
 
 ## Agent DNA
 
-Every agent has a complete behavioral profile built from 4 frameworks:
+Every agent has a behavioral profile from 4 frameworks:
 
-- **DISC** — How they communicate (Driver, Inspirer, Supporter, Analyst)
+- **DISC** — How they communicate
 - **Enneagram** — What motivates them (9 types with wings)
-- **Big Five** — Personality traits on a 0-100 scale
-- **MBTI** — How they process information (16 types, cognitive functions)
-
-This creates agents with consistent, realistic personalities that communicate differently based on their role and the situation.
+- **Big Five** — Personality traits (0-100 scale)
+- **MBTI** — How they process information
 
 ## Quality Gate
 
-Nothing reaches you without approval from all three reviewers:
+Nothing reaches you without all three reviewers:
+
+- **Marta** (CQO) — orchestrates and issues final verdict
+- **Eduardo** — text quality: spelling, grammar, tone, AI patterns
+- **Francisca** — technical quality: code, tests, UX, security
 
-- **Marta** (CQO) orchestrates the review and issues the final verdict
-- **Eduardo** reviews all text: spelling, grammar, tone, AI patterns
-- **Francisca** reviews all technical output: code quality, tests, UX, security
+APPROVED or REJECTED. No exceptions.
 
-Binary verdict: APPROVED or REJECTED. No exceptions. No soft approvals.
+## The Conclave
+
+Personal AI advisory board with 20 real-world advisor personas (Munger, Dalio, Bezos, Naval, Jobs, Sinek, etc.). Matched to your behavioral DNA via 17-question profiling.
+
+```
+/arka conclave         # Start profiling
+/arka conclave ask     # Ask all advisors
+/arka conclave debate  # Advisors debate a topic
+```
 
 ## Enterprise Frameworks
 
-ArkaOS agents don't improvise. They apply validated frameworks:
+ArkaOS agents apply validated frameworks, not generic prompts:
 
 | Area | Frameworks |
 |------|-----------|
-| Development | Clean Code, SOLID, DDD, TDD, DORA Metrics, OWASP Top 10 |
+| Development | Clean Code, SOLID, DDD, TDD, DORA, OWASP, MITRE ATT&CK |
 | Branding | Primal Branding, StoryBrand, 12 Archetypes, Positioning |
 | Strategy | Porter's Five Forces, Blue Ocean, BMC, Wardley Maps, 7 Powers |
-| Finance | DCF Valuation, Unit Economics, COSO ERM, FP&A, Venture Deals |
+| Finance | DCF Valuation, Unit Economics, COSO ERM, ALE Risk Quantification |
 | Marketing | AARRR, Growth Loops, Schwartz 5 Levels, PLG, STEPPS |
-| GTM/Launch | Hormozi Grand Slam, Value Ladder, PLF, Crossing the Chasm |
-| Organization | Team Topologies, Five Dysfunctions, OKRs, Netflix Culture |
-| PM | Scrum, Kanban, Shape Up, Continuous Discovery, Monte Carlo |
+| Compliance | GDPR, ISO 27001, SOC 2, ISO 31000, ISO 9001 |
+| PM | Scrum, Kanban, Shape Up, Continuous Discovery, RICE |
 
 ## Multi-Runtime
 
-ArkaOS works with any AI coding tool:
-
-| Runtime | Status | Features |
-|---------|--------|----------|
-| Claude Code | Primary | Hooks, subagents, MCP, 1M context |
-| Codex CLI | Supported | Subagents, sandboxed execution |
-| Gemini CLI | Supported | Subagents, MCP, 1M context |
-| Cursor | Supported | Agent mode, MCP |
+| Runtime | Status |
+|---------|--------|
+| Claude Code | Primary — hooks, subagents, MCP, 1M context |
+| Codex CLI | Supported — subagents, sandboxed execution |
+| Gemini CLI | Supported — subagents, MCP, 1M context |
+| Cursor | Supported — agent mode, MCP |
 
 ## Architecture
 
 ```
 User Input
   ↓
-Synapse (8-layer context injection, <1ms)
+Synapse (8-layer context injection)
   ↓
 Orchestrator (/do → department routing)
   ↓
@@ -134,21 +156,25 @@ Squad (YAML workflow with phases and gates)
   ↓
 Quality Gate (Marta + Eduardo + Francisca)
   ↓
-Obsidian (all output saved to vault)
+Output (Obsidian vault + structured deliverables)
 ```
 
-Built with: Python core engine, Node.js installer, Bash hooks, YAML workflows.
+Built with: Python core engine, Node.js installer, Bash hooks, YAML workflows, 1688 tests.
 
-## Community & Pro
+## Commands
 
-**Community Edition** (this repo): 56 agents, 16 departments, ~216 commands, full workflow engine.
+```bash
+npx arkaos install      # Install
+npx arkaos update       # Update to latest
+npx arkaos migrate      # Migrate from v1
+npx arkaos doctor       # Health check
+npx arkaos uninstall    # Remove
+```
 
-**Pro** (coming soon): Additional agents, premium skills, knowledge packs, priority support.
+## Contributing
 
-## License
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md). PRs welcome — all changes require review.
 
-MIT
-
----
+## License
 
-**ArkaOS** — WizardingCode
+MIT — [WizardingCode](https://wizardingcode.com)

package/VERSION

@@ -1 +1 @@
-2.0.0
+2.0.1

package/bin/arkaos

@@ -6,7 +6,7 @@
 
 set -euo pipefail
 
-VERSION="2.0.0-alpha.1"
+VERSION=$(node -p "require('$(dirname "$(readlink -f "$0")")/../package.json').version" 2>/dev/null || echo "2.0.0")
 INSTALL_DIR="${HOME}/.arkaos"
 REPO_ROOT=""
 

package/departments/dev/skills/agent-design/SKILL.md

@@ -125,3 +125,7 @@ Surface these issues WITHOUT being asked:
 - Latency budget: <Xms per stage>
 - Cost ceiling: <$ per task>
 ```
+
+## References
+
+- [architecture-patterns.md](references/architecture-patterns.md) — 5 multi-agent patterns with decision matrix, anti-patterns, and scaling characteristics

package/departments/dev/skills/agent-design/references/architecture-patterns.md

@@ -0,0 +1,223 @@
+# Multi-Agent Architecture Patterns — Deep Reference
+
+> 5 patterns with decision criteria, anti-patterns, scaling characteristics, and failure modes.
+
+## Pattern Decision Matrix
+
+| Criterion | Single | Supervisor | Swarm | Hierarchical | Pipeline |
+|-----------|--------|-----------|-------|-------------|----------|
+| Task complexity | Low | Medium | High (emergent) | High (structured) | Medium (sequential) |
+| Agents needed | 1 | 2-10 | 5-50+ | 10-100+ | 3-10 |
+| Coordination overhead | None | Low | High | Medium | Low |
+| Fault tolerance | None | Supervisor is SPOF | High | Medium | Low (chain breaks) |
+| Debuggability | Easy | Medium | Hard | Medium | Easy |
+| Latency | Lowest | Medium | Variable | Higher | Sum of stages |
+
+## Pattern 1: Single Agent
+
+**Structure:** One agent handles all tasks end-to-end.
+
+```
+User --> [Agent] --> Result
+              |
+         [Tool 1] [Tool 2] [Tool 3]
+```
+
+**When to use:**
+- Task scope is narrow and well-defined
+- Fewer than 5 tools needed
+- No parallelism benefit
+- Latency is critical
+
+**Real-world examples:** Code review bot, customer FAQ responder, log summarizer.
+
+**Anti-patterns:**
+- Agent has 10+ tools (cognitive overload, poor tool selection)
+- Agent handles both planning and execution (conflated responsibilities)
+- Agent needs expertise in multiple unrelated domains
+
+**Scaling limit:** Degrades when context window fills or tool count exceeds 5-7.
+
+**Failure modes:**
+
+| Failure | Symptom | Mitigation |
+|---------|---------|------------|
+| Context overflow | Truncated reasoning, lost instructions | Summarize intermediate results |
+| Tool selection errors | Wrong tool called | Reduce tool count, improve descriptions |
+| Single point of failure | Total task failure | Retry with backoff |
+
+## Pattern 2: Supervisor (Hub-and-Spoke)
+
+**Structure:** One coordinator delegates to specialized workers.
+
+```
+User --> [Supervisor]
+            |
+    +-------+-------+
+    |       |       |
+ [Worker] [Worker] [Worker]
+```
+
+**When to use:**
+- Tasks decompose into independent subtasks
+- Need centralized quality control
+- Workers have distinct specializations
+- 2-10 workers
+
+**Real-world examples:** ArkaOS department leads, customer support routing, document processing with specialists (OCR agent, NLP agent, validation agent).
+
+**Anti-patterns:**
+- Supervisor does work instead of delegating (bottleneck)
+- Workers communicate directly bypassing supervisor (untracked state)
+- Single supervisor for 20+ workers (coordination overload)
+
+**Scaling:** Linear with worker count until supervisor becomes bottleneck (~10-15 workers). Fix with hierarchical pattern.
+
+**Failure modes:**
+
+| Failure | Symptom | Mitigation |
+|---------|---------|------------|
+| Supervisor bottleneck | High latency, queued tasks | Add worker-level autonomy |
+| Bad task decomposition | Workers receive incomplete context | Structured handoff schema |
+| Worker failure | Subtask missing from result | Retry policy, fallback workers |
+
+## Pattern 3: Swarm (Peer-to-Peer)
+
+**Structure:** Agents communicate directly, no central coordinator.
+
+```
+[Agent A] <---> [Agent B]
+    ^               ^
+    |               |
+    v               v
+[Agent C] <---> [Agent D]
+```
+
+**When to use:**
+- Problems require emergent solutions
+- No single agent can plan the full solution
+- High parallelism needed
+- Fault tolerance is critical (no SPOF)
+
+**Real-world examples:** Distributed code review (each agent reviews different aspects), brainstorming systems, adversarial debate architectures.
+
+**Anti-patterns:**
+- No termination condition (infinite loops)
+- No shared state schema (agents talk past each other)
+- All agents have identical capabilities (no specialization benefit)
+- No conflict resolution mechanism (contradictory outputs)
+
+**Scaling:** Scales well horizontally but communication complexity grows O(n^2). Use topic-based pub/sub to reduce.
+
+**Failure modes:**
+
+| Failure | Symptom | Mitigation |
+|---------|---------|------------|
+| Infinite loops | Never-ending agent conversations | Max iteration count, convergence check |
+| State divergence | Agents working on stale information | Shared state with version vectors |
+| Deadlock | Agents waiting on each other | Timeout-based resolution |
+| Emergent chaos | Unpredictable outputs | Guardrails on each agent, output validation |
+
+## Pattern 4: Hierarchical (Tree)
+
+**Structure:** Multiple levels of supervisors forming an organizational tree.
+
+```
+            [Executive]
+           /           \
+    [Manager A]     [Manager B]
+    /    \           /    \
+[W1]  [W2]      [W3]  [W4]
+```
+
+**When to use:**
+- Large-scale systems with 10+ agents
+- Natural organizational decomposition (departments, teams)
+- Different abstraction levels needed (strategy vs execution)
+- Need both autonomy and oversight
+
+**Real-world examples:** ArkaOS full system (CTO > Leads > Specialists), enterprise workflow automation, large codebase refactoring.
+
+**Anti-patterns:**
+- Too many hierarchy levels (>3 for most systems, latency compounds)
+- Managers that just pass messages (no value-add at each level)
+- No skip-level communication for urgent issues
+- Rigid hierarchy when tasks cross organizational boundaries
+
+**Scaling:** Best for large systems. Add branches, not depth. Keep depth at 2-3 levels maximum.
+
+**Failure modes:**
+
+| Failure | Symptom | Mitigation |
+|---------|---------|------------|
+| Communication overhead | Slow responses, garbled context | Structured handoff contracts |
+| Middle management bloat | Layers that add latency without value | Audit each level's contribution |
+| Cross-branch coordination | Tasks that need agents from different branches | Ad-hoc squads, matrix overlay |
+| Cascade failure | Manager failure kills entire branch | Fallback managers, worker autonomy |
+
+## Pattern 5: Pipeline (Sequential Chain)
+
+**Structure:** Agents process data in a fixed sequence.
+
+```
+[Input] --> [Stage 1] --> [Stage 2] --> [Stage 3] --> [Output]
+             Extract       Transform      Validate
+```
+
+**When to use:**
+- Processing has a natural sequential order
+- Each stage has a clear input/output contract
+- Stages are independently testable
+- Data transformation workflows
+
+**Real-world examples:** RAG pipeline (chunk > embed > retrieve > rerank > generate), CI/CD pipeline, content moderation (detect > classify > action).
+
+**Anti-patterns:**
+- Stage needs output from a non-adjacent stage (breaks linearity)
+- Stages are tightly coupled (can not test independently)
+- No error handling between stages (silent failures propagate)
+- Pipeline too long (>7 stages, latency compounds)
+
+**Scaling:** Scale individual stages independently. Bottleneck is the slowest stage. Use queues between stages for buffering.
+
+**Failure modes:**
+
+| Failure | Symptom | Mitigation |
+|---------|---------|------------|
+| Stage failure | Pipeline halts | Dead letter queue, skip with default |
+| Bottleneck stage | Throughput limited by slowest stage | Scale that stage, add parallelism |
+| Schema mismatch | Stage receives unexpected input format | Strict contracts, validation between stages |
+| Error propagation | Bad output from stage N corrupts N+1 | Validation gates between stages |
+
+## Pattern Selection Checklist
+
+Use this checklist to narrow down the right pattern:
+
+- [ ] How many distinct agent roles are needed? (1 = Single, 2-10 = Supervisor, 10+ = Hierarchical)
+- [ ] Is the workflow sequential or parallel? (Sequential = Pipeline, Parallel = Supervisor/Swarm)
+- [ ] Is there a natural coordinator? (Yes = Supervisor, No = Swarm)
+- [ ] How important is fault tolerance? (Critical = Swarm, Standard = Supervisor)
+- [ ] What is the latency budget? (Tight = Single/Pipeline, Flexible = Hierarchical)
+- [ ] How debuggable must the system be? (High = Pipeline/Single, Medium = Supervisor)
+
+## Hybrid Patterns
+
+Most production systems combine patterns:
+
+| Hybrid | Structure | Example |
+|--------|-----------|---------|
+| **Supervisor + Pipeline** | Supervisor delegates to pipelines | ArkaOS workflow phases |
+| **Hierarchical + Swarm** | Tree structure with peer collaboration at leaf level | Department leads + specialist brainstorming |
+| **Pipeline + Supervisor** | Pipeline stages contain supervisor-worker teams | ETL where transform stage has multiple workers |
+
+## Token Handoff Cost
+
+| Pattern | Tokens per Handoff | Handoffs per Task | Total Overhead |
+|---------|-------------------|-------------------|----------------|
+| Single | 0 | 0 | 0 |
+| Supervisor | 200-500 | 2-5 | 400-2500 |
+| Pipeline | 300-800 | N stages | 300N-800N |
+| Hierarchical | 200-500 | 2-3 per level | 400-1500 per level |
+| Swarm | 100-300 | Unpredictable | High variance |
+
+Rule of thumb: If total handoff overhead exceeds 30% of useful work tokens, simplify the architecture.

package/departments/dev/skills/ai-security/SKILL.md

@@ -110,3 +110,7 @@ Surface these issues WITHOUT being asked:
 | Priority | Action | Effort | Risk Reduced |
 |----------|--------|--------|-------------|
 ```
+
+## References
+
+- [prompt-injection-catalog.md](references/prompt-injection-catalog.md) — Direct and indirect injection attacks, jailbreaks, data exfiltration via tools, detection patterns, and mitigation strategies