arkaos 2.0.0-alpha.1

package/departments/dev/skills/rag-architect/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: dev/rag-architect
+description: >
+  Design RAG pipelines with chunking strategies, embedding selection,
+  retrieval optimization, and evaluation frameworks.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# RAG Architect — `/dev rag-architect <system>`
+
+> **Agent:** Paulo (Dev Lead) + Andre (Backend) | **Framework:** RAG Pipeline Design
+
+## RAG Pipeline Stages
+
+```
+Documents -> Chunking -> Embedding -> Vector DB -> Retrieval -> Reranking -> Generation
+```
+
+## Chunking Strategies
+
+| Strategy | Best For | Tradeoff |
+|----------|----------|----------|
+| **Fixed-size** (token/char) | Uniform docs, consistent sizes | May break semantic units |
+| **Sentence-based** | Narrative text, articles | Variable chunk sizes |
+| **Paragraph-based** | Structured docs, technical docs | Highly variable sizes |
+| **Semantic** | Long-form, topic shifts | Complex, computationally expensive |
+| **Recursive** | Mixed content types | Optimal utilization, complex logic |
+| **Document-aware** | Multi-format collections | Format-specific implementation |
+
+Rule of thumb: 10-20% overlap between chunks to maintain context continuity.
+
+## Embedding Model Selection
+
+| Category | Model | Dims | Speed | Use Case |
+|----------|-------|------|-------|----------|
+| Fast | all-MiniLM-L6-v2 | 384 | ~14K tok/s | Prototyping, low-latency |
+| Balanced | all-mpnet-base-v2 | 768 | ~2.8K tok/s | Most applications |
+| Quality | text-embedding-ada-002 | 1536 | API | Production, complex domains |
+| Code | CodeBERT / GraphCodeBERT | 768 | Varies | Code search |
+| Multilingual | LaBSE / multilingual-e5 | 768 | Varies | Multi-language corpora |
+
+## Vector Database Comparison
+
+| DB | Type | Best For | Limitation |
+|----|------|----------|-----------|
+| **Pinecone** | Managed | Production, auto-scaling | Vendor lock-in, cost |
+| **Qdrant** | Self-hosted | High performance, low memory | Smaller community |
+| **Weaviate** | Self-hosted/Cloud | Complex data, GraphQL | Learning curve |
+| **Chroma** | Embedded | Dev/testing, prototyping | Not production-scale |
+| **pgvector** | PostgreSQL ext. | Existing PG infra, ACID | Less specialized |
+
+## Retrieval Strategies
+
+| Strategy | Mechanism | When to Use |
+|----------|-----------|------------|
+| **Dense** | Embedding cosine similarity | Semantic matching, paraphrasing |
+| **Sparse** | BM25, TF-IDF | Exact keyword matching |
+| **Hybrid** | Dense + sparse with RRF fusion | Best of both, production default |
+| **Reranking** | Cross-encoder second pass | Higher precision needed |
+
+## Query Transformation Techniques
+
+| Technique | How It Works | Benefit |
+|-----------|-------------|---------|
+| **HyDE** | Generate hypothetical answer, embed that | Matches document style |
+| **Multi-Query** | Generate 3-5 query variations, merge results | Increases recall |
+| **Step-Back** | Broaden query to general form | Better general context |
+
+## Evaluation Metrics
+
+| Metric | Target | Measures |
+|--------|--------|----------|
+| **Faithfulness** | > 90% | Answers grounded in retrieved context |
+| **Context Relevance** | > 0.80 | Retrieved chunks relevant to query |
+| **Answer Relevance** | > 0.85 | Answer addresses the question |
+| **Precision@K** | > 0.70 | Top-K results that are relevant |
+| **MRR** | > 0.75 | Rank of first relevant result |
+
+Use RAGAS framework for comprehensive end-to-end evaluation.
+
+## Design Checklist
+
+- [ ] Chunking strategy selected and tested on sample docs
+- [ ] Embedding model benchmarked for domain
+- [ ] Vector DB chosen based on scale and infra constraints
+- [ ] Retrieval strategy defined (dense/sparse/hybrid)
+- [ ] Reranking layer evaluated for precision gain vs latency
+- [ ] Query transformation tested for recall improvement
+- [ ] Evaluation pipeline set up with ground-truth dataset
+- [ ] Caching strategy defined (query-level, semantic, chunk-level)
+- [ ] Fallback mechanisms for retrieval failures
+- [ ] Cost per query estimated and budgeted
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- Chunk size >2000 tokens with complex data → flag retrieval quality risk
+- No evaluation metrics defined → flag unmeasurable quality
+- Single retrieval strategy → suggest hybrid (semantic + keyword)
+
+## Output
+
+```markdown
+## RAG System Design: <System Name>
+
+### Pipeline
+- **Chunking:** <strategy>, <size>, <overlap>
+- **Embedding:** <model>, <dimensions>
+- **Vector DB:** <database>, <index type>
+- **Retrieval:** <strategy>, top-K=<N>
+- **Reranking:** <model or none>
+
+### Evaluation Targets
+| Metric | Target |
+|--------|--------|
+| Faithfulness | >X% |
+| Context Relevance | >X |
+| Answer Relevance | >X |
+
+### Cost Estimate
+- Embedding cost: ~$X per 1K docs
+- Storage: ~$X/month for <N> vectors
+- Query cost: ~$X per 1K queries
+```

package/departments/dev/skills/red-team/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: dev/red-team
+description: >
+  Offensive security engagement planning: MITRE ATT&CK kill-chain, technique scoring, attack path analysis, OPSEC assessment.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Red Team Engagement — `/dev red-team`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** MITRE ATT&CK, Cyber Kill Chain
+
+**All red team activities require written authorization (signed Rules of Engagement).**
+
+## What It Does
+
+Plans structured adversary simulations using MITRE ATT&CK techniques. Scores attack paths, identifies choke points, assesses OPSEC risks, and targets crown jewel assets.
+
+## Kill-Chain Phases
+
+| Phase | Order | MITRE Tactic | Examples |
+|-------|-------|-------------|----------|
+| Reconnaissance | 1 | TA0043 | T1595, T1596, T1598 |
+| Initial Access | 2 | TA0001 | T1190, T1566, T1078 |
+| Execution | 3 | TA0002 | T1059, T1047, T1204 |
+| Persistence | 4 | TA0003 | T1053, T1543, T1136 |
+| Privilege Escalation | 5 | TA0004 | T1055, T1548, T1134 |
+| Credential Access | 6 | TA0006 | T1003, T1110, T1558 |
+| Lateral Movement | 7 | TA0008 | T1021, T1550, T1534 |
+| Exfiltration / Impact | 8 | TA0010/TA0040 | T1048, T1486, T1491 |
+
+## Access Levels
+
+| Level | Starting Position | Scope |
+|-------|------------------|-------|
+| External | No internal access, internet only | Phishing, public exploits |
+| Internal | Network foothold, no credentials | Internal recon, lateral prep |
+| Credentialed | Valid credentials (assumed breach) | Full kill chain |
+
+## Technique Scoring
+
+```
+effort_score = detection_risk x (prerequisites + 1)
+```
+
+| Technique | Detection Risk | Prerequisites | Effort | MITRE ID |
+|-----------|---------------|---------------|--------|----------|
+| Spearphishing link | 0.4 | none | 0.4 | T1566.001 |
+| Scheduled task | 0.5 | execution | 1.0 | T1053.005 |
+| PowerShell exec | 0.7 | initial_access | 1.4 | T1059.001 |
+| LSASS dump | 0.8 | local_admin | 1.6 | T1003.001 |
+| Pass-the-Hash | 0.6 | cred_access + network | 1.8 | T1550.002 |
+| Ransomware deploy | 0.9 | persist + lateral | 2.7 | T1486 |
+
+## OPSEC Checklist (Before Each Phase)
+
+- [ ] Technique is in scope per Rules of Engagement
+- [ ] Known detection signatures identified for this technique
+- [ ] Less-detectable alternative evaluated
+- [ ] Cleanup artifacts defined for post-exercise removal
+- [ ] If detected, does it reveal the full operation or only current foothold
+
+## Crown Jewel Targeting
+
+| Crown Jewel | Attack Path | Detection Priority |
+|-------------|------------|-------------------|
+| Domain Controller | Kerberoasting, DCSync, Golden Ticket | Highest |
+| Database servers | Lateral movement, DBA account, data staging | High |
+| Payment systems | Network pivot, service account, exfiltration | Highest |
+| Source code repos | VPN, internal git, code signing keys | High |
+| Cloud management | Phishing, credential, AssumeRole chain | Highest |
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails |
+|-------------|-------------|
+| No written authorization | Criminal offense under CFAA and equivalents |
+| Skipping kill-chain order | Single detection wipes all footholds |
+| No crown jewels defined | Drifts into open-ended vulnerability hunting |
+| Avoiding all detectable techniques | Unrealistic engagement, does not validate detection |
+| No real-time documentation | Retroactive logs are unreliable for reporting |
+| Leaving artifacts post-exercise | Creates permanent security risks |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- Default credentials in production → CRITICAL flag
+- No rate limiting on auth endpoints → flag brute force risk
+- Publicly exposed admin panel → flag attack surface
+
+## Output
+
+```markdown
+## Red Team Engagement Plan: <target>
+
+### Authorization: RoE signed <date>, scope: <defined scope>
+### Access Level: <external/internal/credentialed>
+### Crown Jewels: <target assets>
+
+### Kill-Chain Plan
+| Phase | Technique | MITRE ID | Effort | OPSEC Risk |
+|-------|-----------|----------|--------|-----------|
+| Initial Access | Spearphishing | T1566.001 | 0.4 | Low |
+| Execution | PowerShell | T1059.001 | 1.4 | Medium |
+| Credential Access | LSASS dump | T1003.001 | 1.6 | High |
+| Lateral Movement | Pass-the-Hash | T1550.002 | 1.8 | Medium |
+
+### Choke Points: T1003 (credential dump) — blocks 3 attack paths
+### Total Effort Score: 5.2
+### Detection Gaps: <identified gaps in blue team coverage>
+### Recommendation: Focus detection investment on choke point T1003
+```

package/departments/dev/skills/refactor-plan/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/refactor-plan
+description: >
+  Plan a refactoring: identify code smells, select refactoring patterns, ensure test safety net.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Refactor Plan — `/dev refactor <scope>`
+
+> **Agent:** Paulo (Tech Lead) | **Framework:** Refactoring Catalog (Martin Fowler)
+
+## What It Does
+
+Plan a refactoring: identify code smells, select refactoring patterns, ensure test safety net.
+
+## Output
+
+Refactoring plan with patterns, risk assessment, and test verification steps

package/departments/dev/skills/release/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: dev/release
+description: >
+  Release planning and execution: versioning strategy, readiness checklists, deployment coordination, rollback procedures, and hotfix management.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Release Management — `/dev release`
+
+> **Agent:** Paulo (Dev Lead) | **Framework:** SemVer, DORA Metrics, Continuous Delivery
+
+## Versioning Strategy (SemVer)
+
+| Bump | When | Example |
+|------|------|---------|
+| **MAJOR** | Breaking changes, removed APIs | 1.x.x -> 2.0.0 |
+| **MINOR** | New features, backward compatible | 1.2.x -> 1.3.0 |
+| **PATCH** | Bug fixes, security patches | 1.2.3 -> 1.2.4 |
+| **Pre-release** | Alpha/beta/RC testing | 1.3.0-beta.1 |
+
+**Auto-detection from conventional commits:**
+- `feat!:` or `BREAKING CHANGE:` footer -> MAJOR
+- `feat:` -> MINOR
+- `fix:`, `perf:`, `security:` -> PATCH
+- `docs:`, `test:`, `chore:` -> No bump
+
+## Release Readiness Checklist
+
+### Code Quality
+- [ ] All CI checks passing (lint, type-check, build)
+- [ ] Test coverage >= 80%
+- [ ] No critical/high static analysis findings
+- [ ] Security audit clean (`/dev security-audit`)
+- [ ] Dependency audit clean (`/dev dependency-audit`)
+
+### Documentation
+- [ ] CHANGELOG.md updated (`/dev changelog`)
+- [ ] Migration guide written for breaking changes
+- [ ] API documentation reflects changes
+- [ ] Deployment notes prepared
+
+### Approvals
+- [ ] Code review approved
+- [ ] QA validation complete (Marta -- Quality Gate)
+- [ ] Product sign-off on feature scope
+- [ ] Security clearance (if applicable)
+
+## Deployment Sequence
+
+| Phase | Timing | Action |
+|-------|--------|--------|
+| **Code Freeze** | T-24h | No new merges, final validation |
+| **Migrations** | T-2h | Run and validate DB schema changes |
+| **Deploy** | T-0 | Blue-green or canary rollout |
+| **Verify** | T+1h | Monitor error rates, latency, golden signals |
+| **Rollback Window** | T+4h | Go/no-go decision on keeping release |
+
+## Rollback Triggers
+
+| Trigger | Threshold | Action |
+|---------|-----------|--------|
+| Error rate spike | > 2x baseline for 15 min | Auto-rollback or IC decision |
+| Latency degradation | p99 > 2x baseline for 10 min | Investigate, rollback if no fix |
+| Core feature failure | Any critical path broken | Immediate rollback |
+| Data corruption | Any evidence | Immediate rollback + incident |
+
+## Rollback Types
+
+| Type | Method | Notes |
+|------|--------|-------|
+| **Code** | Revert to previous container/build | Fastest, prefer this |
+| **Feature flag** | Disable flag for new code path | No deploy needed |
+| **Database** | Forward-only migration preferred | Never drop columns in rollback |
+| **Infrastructure** | Blue-green switch | DNS propagation delay |
+
+## Hotfix Procedure
+
+| Severity | SLA | Process |
+|----------|-----|---------|
+| **P0** Critical | 2 hours | Emergency branch from last tag, minimal fix, expedited deploy |
+| **P1** High | 24 hours | Expedited review, deploy in next window |
+| **P2** Medium | Next release | Normal PR process |
+
+**Hotfix steps:**
+1. Branch from last stable tag: `git checkout -b hotfix/description vX.Y.Z`
+2. Apply minimal fix (root cause only)
+3. Run automated tests
+4. Deploy with expedited approval
+5. Merge back to main and develop
+6. Schedule PIR for P0/P1
+
+## DORA Metrics to Track
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| **Lead Time** | < 1 day | Commit to production |
+| **Deploy Frequency** | Daily/weekly | Releases per period |
+| **Change Failure Rate** | < 15% | Releases causing incidents |
+| **MTTR** | < 1 hour | Incident to resolution |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- No rollback plan documented → flag deployment risk
+- Breaking change without major version bump → flag SemVer violation
+- Release without changelog entry → flag documentation gap
+
+## Output
+
+```markdown
+## Release Plan: v{X.Y.Z}
+
+### Version Bump: {MAJOR|MINOR|PATCH}
+### Reason: {summary of changes}
+
+### Readiness
+- [ ] Code quality gates: {PASS/FAIL}
+- [ ] Documentation: {PASS/FAIL}
+- [ ] Approvals: {PASS/FAIL}
+
+### Changes Included
+- Features: {count}
+- Fixes: {count}
+- Breaking changes: {count}
+
+### Deployment Strategy: {blue-green / canary / rolling}
+### Rollback Plan: {container revert / feature flag / DB-safe}
+### Risk Assessment: {LOW / MEDIUM / HIGH}
+```

package/departments/dev/skills/research/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/research
+description: >
+  Research a technical topic: library evaluation, pattern comparison, best practice discovery.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Research — `/dev research <topic>`
+
+> **Agent:** Lucas (Analyst) | **Framework:** Context7 + Web Research
+
+## What It Does
+
+Research a technical topic: library evaluation, pattern comparison, best practice discovery.
+
+## Output
+
+Research report with options, trade-offs, and recommendation

package/departments/dev/skills/runbook/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: dev/runbook
+description: >
+  Generate operational runbooks for deployment, incident response, rollback, and scaling procedures.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# Runbook Generator — `/dev runbook`
+
+> **Agent:** Andre (Backend Dev) | **Framework:** SRE (Google), Three Ways (Gene Kim)
+
+## What It Does
+
+Generates structured operational runbooks from service analysis. Covers deployment, health checks, rollback, incident response, and scaling procedures.
+
+## Runbook Sections
+
+| Section | Purpose | Required |
+|---------|---------|----------|
+| Service Overview | Name, owner, dependencies, endpoints | Yes |
+| Health Checks | URLs, expected responses, check intervals | Yes |
+| Deployment | Step-by-step deploy with verification | Yes |
+| Rollback | How to revert, data migration rollback | Yes |
+| Incident Response | Triage, escalation contacts, communication | Yes |
+| Scaling | Horizontal/vertical triggers and procedures | If applicable |
+| Maintenance | Scheduled tasks, backups, log rotation | If applicable |
+
+## Generation Workflow
+
+1. **Analyze** the service: stack, dependencies, infrastructure
+2. **Detect** existing configs: Dockerfile, docker-compose, CI/CD, k8s manifests
+3. **Generate** runbook with copy-pasteable commands
+4. **Validate** every command runs in staging
+5. **Store** runbook alongside service code in version control
+
+## Runbook Quality Checklist
+
+- [ ] Every command is copy-pasteable (no placeholders without explanation)
+- [ ] Every critical step has a verification check after it
+- [ ] Rollback triggers are explicit (what metric/error = rollback)
+- [ ] Escalation contacts are named with phone/Slack
+- [ ] Runbook tested outside of incident conditions
+- [ ] Last review date documented
+
+## Common Pitfalls
+
+| Pitfall | Impact | Prevention |
+|---------|--------|------------|
+| Missing rollback commands | Incident drags on | Mandate rollback section in review |
+| Steps without verification | Silent failures | Add expected output after each step |
+| Stale contacts | Escalation fails | Review contacts quarterly |
+| Never tested | Fails during incident | Dry-run in staging monthly |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- Production service without runbook → flag operational risk
+- Runbook >6 months without update → flag stale procedures
+- No rollback section in deployment runbook → flag recovery gap
+
+## Output
+
+```markdown
+## Runbook: <service-name>
+
+### Service Overview
+- **Owner:** <team/person>
+- **Stack:** <e.g., Laravel 11, PostgreSQL 16, Redis 7>
+- **Dependencies:** <upstream/downstream services>
+- **Endpoints:** <health, API base URL>
+
+### Health Checks
+| Check | URL/Command | Expected | Interval |
+|-------|------------|----------|----------|
+| HTTP health | GET /health | 200 OK | 30s |
+| DB connection | `php artisan db:monitor` | Connected | 60s |
+| Queue depth | `redis-cli llen queues:default` | < 1000 | 60s |
+
+### Deployment
+1. `git pull origin main`
+2. `composer install --no-dev --optimize-autoloader`
+3. `php artisan migrate --force`
+   Verify: `php artisan migrate:status` shows all ran
+4. `php artisan config:cache && php artisan route:cache`
+5. `sudo systemctl reload php-fpm`
+   Verify: GET /health returns 200
+
+### Rollback
+**Trigger:** Error rate > 5% or p99 latency > 2s post-deploy
+1. `git checkout <previous-tag>`
+2. `composer install --no-dev`
+3. `php artisan migrate:rollback --step=1`
+4. `sudo systemctl reload php-fpm`
+   Verify: GET /health returns 200, error rate normalizes
+
+### Incident Response
+1. **Triage:** Check /health, logs (`tail -f storage/logs/laravel.log`)
+2. **Escalate:** <contact name> — Slack #incidents / phone
+3. **Communicate:** Post in #status-page within 10 minutes
+4. **Resolve:** Apply fix or rollback
+5. **Postmortem:** Within 48 hours, update this runbook
+```