arkaos 2.0.0 → 2.0.2

package/departments/ops/skills/quality-management/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: ops/quality-management
+description: >
+  Quality management system design, process improvement, internal audit management, and management review per ISO 9001.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Quality Management — `/ops quality-management`
+
+> **Agent:** Daniel (Ops Lead) | **Framework:** ISO 9001:2015, QMS, PDCA Cycle
+
+## QMS Implementation Phases
+
+| Phase | PDCA | Activities | Deliverables |
+|-------|------|-----------|-------------|
+| 1. Context & Scope | Plan | Interested parties, scope, process map | Context document, scope statement |
+| 2. Leadership | Plan | Quality policy, objectives, roles | Policy, RACI, objectives |
+| 3. Planning | Plan | Risk-based thinking, quality objectives | Risk register, action plans |
+| 4. Support | Do | Resources, competence, awareness, documentation | Training plan, doc control |
+| 5. Operation | Do | Process execution, control of outputs | Procedures, work instructions |
+| 6. Evaluation | Check | Monitoring, internal audit, management review | Audit reports, review minutes |
+| 7. Improvement | Act | Nonconformity, CAPA, continual improvement | CAPA records, improvement log |
+
+## Quality KPIs Dashboard
+
+| Category | KPI | Target | Calculation |
+|----------|-----|--------|------------|
+| Process | First Pass Yield | > 95% | (Units passed first / Total) x 100 |
+| Process | Nonconformance Rate | < 1% | (NC count / Total) x 100 |
+| CAPA | Closure Rate (on-time) | > 90% | (On-time closures / Due) x 100 |
+| CAPA | Effectiveness Rate | > 85% | (Effective / Verified) x 100 |
+| Audit | Finding Closure Rate | > 90% | (Closed on time / Total due) x 100 |
+| Audit | Repeat Finding Rate | < 10% | (Repeats / Total findings) x 100 |
+| Customer | Complaint Rate | < 0.1% | (Complaints / Units) x 100 |
+| Customer | Satisfaction Score | > 4.0/5.0 | Average survey score |
+
+## Internal Audit Program
+
+| Risk Level | Audit Frequency | Scope |
+|-----------|----------------|-------|
+| High | Quarterly | Critical processes, customer-facing |
+| Medium | Semi-annual | Supporting processes |
+| Low | Annual | Administrative processes |
+
+### Audit Workflow
+1. Define annual audit schedule based on process risk
+2. Assign auditors (independent from audited area)
+3. Prepare audit plan and checklist per ISO 9001 clauses
+4. Conduct audit: opening meeting, evidence collection, closing
+5. Document findings: major NC, minor NC, observation, opportunity
+6. Issue corrective action requests with deadlines
+7. Verify corrective action effectiveness
+8. Report results to management review
+
+## Management Review Inputs (ISO 9001 Clause 9.3.2)
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Previous review actions | Review records | Yes |
+| Changes in external/internal issues | Context monitoring | Yes |
+| Customer satisfaction and feedback | Surveys, complaints | Yes |
+| Quality objectives achievement | KPI reports | Yes |
+| Process performance and product conformity | Process metrics | Yes |
+| Nonconformities and corrective actions | CAPA system | Yes |
+| Audit results | Internal/external audits | Yes |
+| Supplier performance | Supplier scorecards | Yes |
+| Improvement opportunities | All sources | Yes |
+
+## CAPA Process
+
+| Step | Activity | Timeline | Owner |
+|------|----------|----------|-------|
+| 1 | Identify nonconformity or improvement need | Immediate | Anyone |
+| 2 | Contain immediate effects | 24-48 hours | Process owner |
+| 3 | Root cause analysis (5 Whys, Ishikawa, 8D) | 10 days | CAPA owner |
+| 4 | Define corrective/preventive actions | 5 days | CAPA owner |
+| 5 | Implement actions | Per plan | Assigned |
+| 6 | Verify effectiveness | 30-90 days | Quality |
+| 7 | Close and update documentation | 5 days | Quality |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- No CAPA process defined or CAPA backlog exceeding SLA -> flag as ISO 9001 Clause 10.2 nonconformity risk
+- Management review overdue or not conducted within scheduled period -> flag as Clause 9.3 requirement gap
+- No internal audit schedule or audit program not covering all QMS processes -> flag as Clause 9.2 compliance gap
+
+## Output
+
+```markdown
+## Quality Management Assessment: <organization>
+
+### QMS Maturity: <Initial | Documented | Implemented | Measured | Optimizing>
+
+### KPI Summary
+| KPI | Current | Target | Status |
+|-----|---------|--------|--------|
+
+### Audit Program Status
+- Audits completed: X/X planned
+- Open findings: X (major: X, minor: X)
+- Overdue CAPAs: X
+
+### Process Performance
+- Processes meeting targets: X/X
+- Processes requiring intervention: X
+
+### Recommendations
+1. [Priority] Action — Timeline — Owner
+
+### Next Management Review: <date>
+```
+
+## References
+
+- [iso9001-implementation.md](references/iso9001-implementation.md) — ISO 9001:2015 clause-by-clause guidance, process approach, documentation requirements
+- [capa-methodology.md](references/capa-methodology.md) — Root cause analysis techniques, corrective action planning, effectiveness verification

package/departments/ops/skills/risk-management/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ops/risk-management
+description: >
+  Enterprise risk identification, assessment, treatment, and monitoring using ISO 31000 and COSO ERM frameworks.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Risk Management — `/ops risk-management`
+
+> **Agent:** Daniel (Ops Lead) | **Framework:** ISO 31000:2018, COSO ERM (2017)
+
+## Risk Management Process (ISO 31000)
+
+| Phase | Activities | Deliverables |
+|-------|-----------|-------------|
+| 1. Scope & Context | Define objectives, stakeholders, risk criteria | Context statement, risk appetite |
+| 2. Risk Identification | Identify sources, events, causes, consequences | Risk register (initial) |
+| 3. Risk Analysis | Assess likelihood and impact, determine risk level | Risk scores, risk matrix |
+| 4. Risk Evaluation | Compare against criteria, prioritize for treatment | Prioritized risk list |
+| 5. Risk Treatment | Select and implement treatment options | Treatment plans, residual risk |
+| 6. Monitoring & Review | Track risks, review effectiveness, update register | Updated register, reports |
+| 7. Communication | Report to stakeholders, escalate as needed | Risk reports, dashboards |
+
+## Risk Identification Techniques
+
+| Technique | Best For | Output |
+|-----------|---------|--------|
+| Brainstorming | Broad risk discovery | Raw risk list |
+| SWOT Analysis | Strategic risks | Categorized risk themes |
+| Checklist Analysis | Known risk categories | Validated risk list |
+| Process Flow Analysis | Operational risks | Process-linked risks |
+| Scenario Analysis | Emerging/future risks | Scenario-based risk descriptions |
+| Root Cause Analysis | Understanding risk drivers | Causal chains |
+
+## Risk Assessment Matrix (5x5)
+
+| Likelihood / Impact | Insignificant (1) | Minor (2) | Moderate (3) | Major (4) | Catastrophic (5) |
+|---------------------|-------------------|-----------|-------------|-----------|------------------|
+| Almost Certain (5) | 5 Medium | 10 High | 15 High | 20 Critical | 25 Critical |
+| Likely (4) | 4 Low | 8 Medium | 12 High | 16 Critical | 20 Critical |
+| Possible (3) | 3 Low | 6 Medium | 9 Medium | 12 High | 15 High |
+| Unlikely (2) | 2 Low | 4 Low | 6 Medium | 8 Medium | 10 High |
+| Rare (1) | 1 Low | 2 Low | 3 Low | 4 Low | 5 Medium |
+
+## Risk Treatment Options
+
+| Strategy | When to Use | Example |
+|----------|------------|---------|
+| Avoid | Risk exceeds appetite, activity not essential | Cancel project, exit market |
+| Mitigate | Risk can be reduced to acceptable level | Add controls, improve processes |
+| Transfer | Third party better positioned to manage | Insurance, outsourcing, contracts |
+| Accept | Risk within appetite, cost of treatment exceeds benefit | Document rationale, monitor |
+
+## Risk Register Template
+
+| Field | Description |
+|-------|------------|
+| Risk ID | Unique identifier (R-001) |
+| Category | Strategic / Operational / Financial / Compliance / Reputational |
+| Description | Clear statement of risk event and consequence |
+| Owner | Person accountable for managing the risk |
+| Likelihood | 1-5 rating with justification |
+| Impact | 1-5 rating with justification |
+| Inherent Risk | L x I score before treatment |
+| Treatment | Avoid / Mitigate / Transfer / Accept |
+| Controls | Specific controls or actions in place |
+| Residual Risk | L x I score after treatment |
+| Status | Open / In Treatment / Monitored / Closed |
+| Review Date | Next scheduled review |
+
+## COSO ERM Components
+
+| Component | Focus | Key Activities |
+|-----------|-------|---------------|
+| Governance & Culture | Tone at the top | Risk oversight, operating structure, values |
+| Strategy & Objective Setting | Risk appetite | Business context, risk appetite, strategy alignment |
+| Performance | Risk identification | Identify, assess, prioritize, implement responses |
+| Review & Revision | Monitoring | Substantial change assessment, performance review |
+| Information & Communication | Reporting | Risk information systems, stakeholder reporting |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- Risk register older than 6 months without review -> flag as ISO 31000 Clause 6.7 monitoring gap
+- No risk appetite or tolerance defined by leadership -> flag as governance gap blocking effective risk evaluation
+- Critical risk identified without documented mitigation plan -> flag as unacceptable exposure requiring immediate treatment
+
+## Output
+
+```markdown
+## Risk Assessment: <organization/project>
+
+### Risk Profile Summary
+- Total risks identified: X
+- Critical: X | High: X | Medium: X | Low: X
+
+### Top 5 Risks
+| Rank | Risk | Category | Inherent | Treatment | Residual | Owner |
+|------|------|----------|----------|-----------|----------|-------|
+
+### Risk Appetite Alignment
+- Risks within appetite: X/X
+- Risks exceeding appetite: X (treatment plans required)
+
+### Treatment Plan Status
+- Plans defined: X/X critical+high risks
+- Controls implemented: X/X
+- Effectiveness verified: X/X
+
+### Recommendations
+1. [Priority] Action — Timeline — Owner
+
+### Next Review: <date>
+```
+
+## References
+
+- [iso31000-guide.md](references/iso31000-guide.md) — ISO 31000 principles, framework, process, risk criteria, treatment selection
+- [coso-erm-framework.md](references/coso-erm-framework.md) — COSO ERM components, principles, risk appetite, strategy integration

package/departments/ops/skills/soc2-compliance/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ops/soc2-compliance
+description: >
+  SOC 2 readiness assessment, Trust Services Criteria mapping, control matrix generation, evidence collection, and audit preparation.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# SOC 2 Compliance — `/ops soc2-compliance`
+
+> **Agent:** Daniel (Ops Lead) | **Framework:** SOC 2 Type I/II (AICPA), Trust Services Criteria
+
+## Type I vs Type II
+
+| Aspect | Type I | Type II |
+|--------|--------|---------|
+| Scope | Control design at a point in time | Design AND operating effectiveness over a period |
+| Duration | Snapshot (single date) | Observation window (6-12 months) |
+| Evidence | Policies, control descriptions | Policies + operating evidence (logs, tickets, configs) |
+| Cost | $20K-$50K | $30K-$100K+ |
+| Best For | First-time compliance | Mature organizations, enterprise customers |
+
+## Trust Services Criteria
+
+| Category | Criteria | Required | Focus |
+|----------|---------|----------|-------|
+| Security | CC1-CC9 | Yes (always) | Access, operations, change management, risk |
+| Availability | A1 | Optional | Uptime, DR/BCP, capacity planning |
+| Confidentiality | C1 | Optional | Data classification, encryption, disposal |
+| Processing Integrity | PI1 | Optional | Accuracy, completeness, timeliness |
+| Privacy | P1-P8 | Optional | Notice, consent, collection, retention |
+
+## Security Common Criteria (Required)
+
+| Criteria | Domain | Key Controls |
+|----------|--------|-------------|
+| CC1 | Control Environment | Integrity, oversight, org structure, accountability |
+| CC2 | Communication | Internal/external communication, information quality |
+| CC3 | Risk Assessment | Risk identification, fraud risk, change analysis |
+| CC4 | Monitoring | Ongoing monitoring, deficiency evaluation |
+| CC5 | Control Activities | Policies, technology controls |
+| CC6 | Logical & Physical Access | Provisioning, authentication, encryption |
+| CC7 | System Operations | Vulnerability management, incident response |
+| CC8 | Change Management | Authorization, testing, approval |
+| CC9 | Risk Mitigation | Vendor and business partner risk |
+
+## Evidence Collection Matrix
+
+| Control Area | Primary Evidence | Secondary Evidence |
+|-------------|-----------------|-------------------|
+| Access Management | User access reviews, provisioning tickets | Role matrix, access logs |
+| Change Management | Change tickets, approval records | Deployment logs, test results |
+| Incident Response | Incident tickets, postmortems | Runbooks, escalation records |
+| Vulnerability Mgmt | Scan reports, patch records | Remediation timelines |
+| Encryption | Config screenshots, certificate inventory | Key rotation logs |
+| Backup & Recovery | Backup logs, DR test results | Recovery time measurements |
+| Vendor Management | Vendor assessments, SOC reports | Contract reviews, risk registers |
+
+## Audit Readiness Checklist
+
+- [ ] All controls documented with descriptions, owners, and frequencies
+- [ ] Evidence collected for entire observation period (Type II)
+- [ ] Control matrix reviewed and gaps remediated
+- [ ] Policies signed and distributed within last 12 months
+- [ ] Access reviews completed at required frequency
+- [ ] Vulnerability scans current (no critical/high unpatched beyond SLA)
+- [ ] Incident response plan tested within last 12 months
+- [ ] Vendor risk assessments current for all subservice organizations
+- [ ] DR/BCP tested and documented within last 12 months
+- [ ] Employee security training completed for all staff
+
+### Readiness Scoring
+
+| Score | Rating | Action |
+|-------|--------|--------|
+| 90-100% | Audit Ready | Proceed with confidence |
+| 75-89% | Minor Gaps | Address before scheduling audit |
+| 50-74% | Significant Gaps | Remediation required |
+| < 50% | Not Ready | Major program build-out needed |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- No evidence collection process in place for controls -> flag as audit failure risk requiring immediate process setup
+- Control gaps identified in Trust Services Criteria coverage -> flag as SOC 2 scope gap needing remediation plan
+- Vendor processing customer data without a SOC 2 report or equivalent -> flag as CC9 vendor risk deficiency
+
+## Output
+
+```markdown
+## SOC 2 Readiness Assessment: <organization>
+
+### Target: Type <I/II> | Categories: <Security, Availability, ...>
+
+### Readiness Score: X% — <Rating>
+
+### Control Matrix Summary
+- Controls mapped: X
+- Fully implemented: X | Partial: X | Missing: X
+
+### Evidence Status
+- Evidence collected: X/X controls
+- Automation coverage: X%
+
+### Gap Analysis
+| Priority | Gap | TSC Ref | Remediation | Owner | Target |
+|----------|-----|---------|-------------|-------|--------|
+
+### Vendor Assessment Status
+- Critical vendors assessed: X/X
+- SOC reports on file: X/X
+
+### Recommended Timeline
+Gap Assessment -> Remediation -> Type I -> Observation -> Type II
+```
+
+## References
+
+- [trust-service-criteria.md](references/trust-service-criteria.md) — All 5 TSC categories with sub-criteria, control objectives, and evidence examples
+- [evidence-collection-guide.md](references/evidence-collection-guide.md) — Evidence types per control, automation approaches, documentation requirements

package/departments/strategy/skills/cto-advisor/SKILL.md

@@ -111,3 +111,7 @@ Surface these issues WITHOUT being asked:
 ```
 
 ## Output -> Obsidian: `WizardingCode/Strategy/CTO/ADVISORY-<topic>-<date>.md`
+
+## References
+
+- [build-vs-buy-framework.md](references/build-vs-buy-framework.md) — Evaluation criteria, TCO calculation template, risk matrix, vendor assessment checklist, and decision tree

package/departments/strategy/skills/cto-advisor/references/build-vs-buy-framework.md

@@ -0,0 +1,190 @@
+# Build vs Buy Decision Framework — Deep Reference
+
+> Companion to `cto-advisor/SKILL.md`. Evaluation criteria, TCO templates, risk matrices, and decision trees.
+
+## Decision Tree
+
+```
+START: Does this capability differentiate us from competitors?
+  YES --> Is the domain well-understood (low technical uncertainty)?
+    YES --> BUILD (core IP, known problem)
+    NO  --> BUILD with PROTOTYPE first (validate feasibility before committing)
+  NO  --> Does a vendor solution meet >= 70% of requirements?
+    YES --> Is vendor lock-in risk acceptable?
+      YES --> BUY
+      NO  --> BUY with ABSTRACTION LAYER (wrap vendor behind interface)
+    NO  --> Is this a temporary need (< 18 months)?
+      YES --> BUY cheapest option, plan to revisit
+      NO  --> BUILD (no vendor fits, long-term need)
+```
+
+## Evaluation Criteria Matrix
+
+| Criterion | Weight | Score 1 (Buy) | Score 5 | Score 9 (Build) |
+|-----------|--------|---------------|---------|-----------------|
+| **Core IP relevance** | 30% | Commodity (auth, email) | Supporting feature | Core differentiator |
+| **3-year TCO** | 25% | Buy is 3x cheaper | Comparable | Build is 3x cheaper |
+| **Migration risk** | 20% | Easy to switch vendors | Moderate effort | Vendor lock-in is severe |
+| **Vendor stability** | 15% | Profitable, public company | Funded startup | Pre-revenue, single founder |
+| **Integration effort** | 10% | Drop-in, < 1 week | 2-4 weeks | > 2 months custom work |
+
+### Scoring Template
+
+```markdown
+## Build vs Buy: [Capability Name]
+
+| Criterion | Weight | Build Score | Buy Score | Build Weighted | Buy Weighted |
+|-----------|--------|:-----------:|:---------:|:--------------:|:------------:|
+| Core IP relevance | 30% | _ /9 | _ /9 | _ | _ |
+| 3-year TCO | 25% | _ /9 | _ /9 | _ | _ |
+| Migration risk | 20% | _ /9 | _ /9 | _ | _ |
+| Vendor stability | 15% | _ /9 | _ /9 | _ | _ |
+| Integration effort | 10% | _ /9 | _ /9 | _ | _ |
+| **TOTAL** | 100% | | | **_** | **_** |
+
+Decision: [BUILD / BUY] — [one-sentence rationale]
+```
+
+## Total Cost of Ownership (TCO) — 3-Year Template
+
+### Build TCO
+
+| Cost Category | Year 1 | Year 2 | Year 3 | 3-Year Total |
+|---------------|--------|--------|--------|-------------|
+| Design and architecture | $ | - | - | $ |
+| Development (engineer-months x rate) | $ | $ | $ | $ |
+| Infrastructure (hosting, CI/CD) | $ | $ | $ | $ |
+| Testing and QA | $ | $ | $ | $ |
+| Maintenance (bugs, patches, upgrades) | - | $ | $ | $ |
+| On-call and incident response | - | $ | $ | $ |
+| Documentation and training | $ | $ | $ | $ |
+| Opportunity cost (what else could team build?) | $ | $ | $ | $ |
+| **Subtotal** | **$** | **$** | **$** | **$** |
+
+### Buy TCO
+
+| Cost Category | Year 1 | Year 2 | Year 3 | 3-Year Total |
+|---------------|--------|--------|--------|-------------|
+| License or subscription | $ | $ | $ | $ |
+| Implementation and setup | $ | - | - | $ |
+| Integration development | $ | $ | $ | $ |
+| Data migration | $ | - | - | $ |
+| Training (team onboarding) | $ | $ | $ | $ |
+| Customization and workarounds | $ | $ | $ | $ |
+| Vendor support tier | $ | $ | $ | $ |
+| Price increase risk (estimate 10-15%/yr) | - | $ | $ | $ |
+| Exit cost (migration away if needed) | - | - | $ | $ |
+| **Subtotal** | **$** | **$** | **$** | **$** |
+
+### Hidden Costs Checklist
+
+| Often Missed | Applies to | Typical Impact |
+|-------------|-----------|---------------|
+| Onboarding new engineers to custom system | Build | 2-4 weeks per hire |
+| Vendor API rate limits forcing architecture changes | Buy | 1-3 months rework |
+| Security patching and compliance for custom code | Build | 10-20% of dev time |
+| Vendor sunset or acquisition (forced migration) | Buy | 3-12 months disruption |
+| Feature requests blocked by vendor roadmap | Buy | Lost revenue or workarounds |
+| Scaling custom infrastructure beyond initial design | Build | Major refactor |
+
+## Risk Matrix
+
+### Build Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|:-----------:|:------:|-----------|
+| Underestimated scope (2-3x initial estimate) | High | High | Prototype first, time-box Phase 1 |
+| Key engineer leaves | Medium | High | Document architecture, pair programming |
+| Technical debt accumulates | High | Medium | Allocate 20% capacity for maintenance |
+| Security vulnerabilities in custom code | Medium | High | Security review, penetration testing |
+| Feature creep beyond original scope | High | Medium | Strict ADR governance, MVP discipline |
+
+### Buy Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|:-----------:|:------:|-----------|
+| Vendor increases price significantly | Medium | Medium | Contract with price caps, evaluate alternatives |
+| Vendor gets acquired or shuts down | Low | Critical | Data export plan, abstraction layer |
+| Vendor roadmap diverges from your needs | Medium | High | Evaluate vendor responsiveness, contract SLAs |
+| Data portability limitations | Medium | High | Test data export before committing |
+| Vendor outage affects your availability | Medium | High | SLA with credits, failover plan |
+| Compliance requirements vendor cannot meet | Low | Critical | Verify certifications before purchase |
+
+## Vendor Assessment Checklist
+
+### Must-Have (Dealbreakers)
+
+- [ ] Meets >= 70% of functional requirements
+- [ ] API available for integration (no manual-only workflows)
+- [ ] Data export capability (no vendor lock-in on data)
+- [ ] Compliance certifications you need (SOC 2, GDPR, HIPAA)
+- [ ] Uptime SLA >= 99.9% with credits
+- [ ] Security practices documented (encryption, access controls)
+
+### Should-Have (Differentiators)
+
+- [ ] Active development (releases in last 90 days)
+- [ ] Community or ecosystem (plugins, integrations, forums)
+- [ ] Transparent pricing (no "contact sales" for basic tier)
+- [ ] Multi-region availability
+- [ ] SSO/SAML support
+- [ ] Audit logs and admin controls
+- [ ] Sandbox/staging environment available
+
+### Red Flags
+
+| Signal | Risk | Action |
+|--------|------|--------|
+| No public pricing | Enterprise lock-in | Get written pricing with caps |
+| No data export feature | Vendor lock-in | Negotiate contractual export rights |
+| Single founder, no funding | Business continuity | Escrow agreement for source code |
+| No SOC 2 or equivalent | Security gaps | Assess if your compliance requires it |
+| API is an afterthought (limited, poorly documented) | Integration pain | Build POC before committing |
+| Customer success requires professional services | Hidden cost | Factor into TCO |
+
+## Migration Cost Estimation
+
+### From Build to Buy
+
+| Phase | Effort | Duration |
+|-------|--------|----------|
+| Vendor evaluation and POC | 1-2 engineers, 2-4 weeks | 1 month |
+| Data migration planning and scripting | 1-2 engineers, 2-4 weeks | 1 month |
+| Integration development | 2-3 engineers, 4-8 weeks | 2 months |
+| Testing and validation | 1-2 engineers, 2-4 weeks | 1 month |
+| Cutover and decommission | 1 engineer, 1-2 weeks | 2 weeks |
+| **Total** | **5-10 engineer-months** | **4-6 months** |
+
+### From Buy to Build
+
+| Phase | Effort | Duration |
+|-------|--------|----------|
+| Requirements from vendor feature usage | 1 engineer, 2 weeks | 2 weeks |
+| Architecture and design | 1-2 engineers, 2-4 weeks | 1 month |
+| Core development (MVP) | 2-4 engineers, 8-16 weeks | 3-4 months |
+| Data migration from vendor | 1-2 engineers, 2-4 weeks | 1 month |
+| Feature parity (remaining 30%) | 2-3 engineers, 4-8 weeks | 2 months |
+| **Total** | **10-20 engineer-months** | **6-9 months** |
+
+## Decision Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Better Approach |
+|-------------|-------------|-----------------|
+| "We can build it in a weekend" | Maintenance is 80% of lifetime cost | Estimate with 3x multiplier for Year 2-3 |
+| "Vendor X is too expensive" | Compare to full build cost, not just license | Calculate 3-year TCO for both |
+| "Not invented here" (always build) | Team builds commodity features | Build only what differentiates |
+| "Just buy everything" (always buy) | Death by a thousand subscriptions | Own your core IP |
+| "Let's build now, buy later" | Migration cost is often higher than starting with buy | Decide once, commit for 2+ years |
+| Committee decision with no owner | Endless evaluation, no decision | Assign single decision owner with deadline |
+
+## Hybrid Strategy: Buy + Extend
+
+Sometimes the best answer is neither pure build nor pure buy:
+
+| Pattern | When | Example |
+|---------|------|---------|
+| Buy + API integration | Core vendor, custom workflows | Stripe + custom billing logic |
+| Buy + plugin/extension | Vendor supports extensibility | Shopify + custom app |
+| Buy + abstraction layer | Hedge against vendor lock-in | Interface over any email provider |
+| Buy + custom UI | Vendor backend, your UX | Headless CMS + custom frontend |
+| Open source + self-host | Need control, community does heavy lifting | PostgreSQL, Redis, Grafana |

package/installer/cli.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 
 import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { install } from "./index.js";
 import { detectRuntime } from "./detect-runtime.js";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
+
 const { values, positionals } = parseArgs({
   options: {
     help: { type: "boolean", short: "h" },
@@ -16,7 +22,6 @@ const { values, positionals } = parseArgs({
   strict: false,
 });
 
-const VERSION = "2.0.0-alpha.1";
 const command = positionals[0] || "install";
 
 if (values.version) {
@@ -31,8 +36,9 @@ ArkaOS v${VERSION} — The Operating System for AI Agent Teams
 Usage:
   npx arkaos install          Install ArkaOS in current environment
   npx arkaos install --runtime <runtime>  Install for specific runtime
-  npx arkaos doctor           Run health checks
   npx arkaos update           Update to latest version
+  npx arkaos migrate          Migrate from v1 to v2
+  npx arkaos doctor           Run health checks
   npx arkaos uninstall        Remove ArkaOS
 
 Options:
@@ -78,6 +84,11 @@ async function main() {
       await uninstall();
       break;
 
+    case "migrate":
+      const { migrate } = await import("./migrate.js");
+      await migrate();
+      break;
+
     default:
       console.error(`Unknown command: ${command}`);
       console.error('Run "npx arkaos help" for usage information.');

package/installer/index.js

@@ -8,8 +8,7 @@ import { getRuntimeConfig } from "./detect-runtime.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ARKAOS_ROOT = resolve(__dirname, "..");
-
-const VERSION = "2.0.0-alpha.1";
+const VERSION = JSON.parse(readFileSync(join(ARKAOS_ROOT, "package.json"), "utf-8")).version;
 
 export async function install({ runtime, path, force }) {
   console.log(`\n  ArkaOS v${VERSION} — The Operating System for AI Agent Teams\n`);