@monoes/monomindcli 2.15.2 → 2.15.4

package/org-skills/cto-advisor/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: cto-advisor
+description: "Technical leadership guidance for engineering teams, architecture decisions, and technology strategy. Use when assessing technical debt, scaling engineering teams, evaluating technologies, making architecture decisions, establishing engineering metrics, or when user mentions CTO, tech debt, technical debt, team scaling, architecture decisions, technology evaluation, engineering metrics, DORA..."
+tags: ["leadership","engineering"]
+tools: []
+license: MIT
+source: https://github.com/alirezarezvani/claude-skills
+source_path: "c-level-advisor/skills/cto-advisor"
+source_commit: 19392f7a08264ed00486a251f5b2098321771f94
+---
+# CTO Advisor
+
+Technical leadership frameworks for architecture, engineering teams, technology strategy, and technical decision-making.
+
+## Keywords
+CTO, chief technology officer, tech debt, technical debt, architecture, engineering metrics, DORA, team scaling, technology evaluation, build vs buy, cloud migration, platform engineering, AI/ML strategy, system design, incident response, engineering culture
+
+## Quick Start
+
+```bash
+python scripts/tech_debt_analyzer.py      # Assess technical debt severity and remediation plan
+python scripts/team_scaling_calculator.py  # Model engineering team growth and cost
+```
+
+## Core Responsibilities
+
+### 1. Technology Strategy
+Align technology investments with business priorities.
+
+**Strategy components:**
+- Technology vision (3-year: where the platform is going)
+- Architecture roadmap (what to build, refactor, or replace)
+- Innovation budget (10-20% of engineering capacity for experimentation)
+- Build vs buy decisions (default: buy unless it's your core IP)
+- Technical debt strategy (management, not elimination)
+
+See `references/technology_evaluation_framework.md` for the full evaluation framework.
+
+### 2. Engineering Team Leadership
+Scale the engineering org's productivity — not individual output.
+
+**Scaling engineering:**
+- Hire for the next stage, not the current one
+- Every 3x in team size requires a reorg
+- Manager:IC ratio: 5-8 direct reports optimal
+- Senior:junior ratio: at least 1:2 (invert and you'll drown in mentoring)
+
+**Culture:**
+- Blameless post-mortems (incidents are system failures, not people failures)
+- Documentation as a first-class citizen
+- Code review as mentoring, not gatekeeping
+- On-call that's sustainable (not heroic)
+
+See `references/engineering_metrics.md` for DORA metrics and the engineering health dashboard.
+
+### 3. Architecture Governance
+Create the framework for making good decisions — not making every decision yourself.
+
+**Architecture Decision Records (ADRs):**
+- Every significant decision gets documented: context, options, decision, consequences
+- Decisions are discoverable (not buried in Slack)
+- Decisions can be superseded (not permanent)
+
+See `references/architecture_decision_records.md` for ADR templates and the decision review process.
+
+### 4. Vendor & Platform Management
+Every vendor is a dependency. Every dependency is a risk.
+
+**Evaluation criteria:** Does it solve a real problem? Can we migrate away? Is the vendor stable? What's the total cost (license + integration + maintenance)?
+
+### 5. Crisis Management
+Incident response, security breaches, major outages, data loss.
+
+**Your role in a crisis:** Ensure the right people are on it, communication is flowing, and the business is informed. Post-crisis: blameless retrospective within 48 hours.
+
+## Workflows
+
+### Tech Debt Assessment Workflow
+
+**Step 1 — Run the analyzer**
+```bash
+python scripts/tech_debt_analyzer.py --output report.json
+```
+
+**Step 2 — Interpret results**
+The analyzer produces a severity-scored inventory. Review each item against:
+- Severity (P0–P3): how much is it blocking velocity or creating risk?
+- Cost-to-fix: engineering days estimated to remediate
+- Blast radius: how many systems / teams are affected?
+
+**Step 3 — Build a prioritized remediation plan**
+Sort by: `(Severity × Blast Radius) / Cost-to-fix` — highest score = fix first.
+Group items into: (a) immediate sprint, (b) next quarter, (c) tracked backlog.
+
+**Step 4 — Validate before presenting to stakeholders**
+- [ ] Every P0/P1 item has an owner and a target date
+- [ ] Cost-to-fix estimates reviewed with the relevant tech lead
+- [ ] Debt ratio calculated: maintenance work / total engineering capacity (target: < 25%)
+- [ ] Remediation plan fits within capacity (don't promise 40 points of debt reduction in a 2-week sprint)
+
+**Example output — Tech Debt Inventory:**
+```
+Item                  | Severity | Cost-to-Fix | Blast Radius | Priority Score
+----------------------|----------|-------------|--------------|---------------
+Auth service (v1 API) | P1       | 8 days      | 6 services   | HIGH
+Unindexed DB queries  | P2       | 3 days      | 2 services   | MEDIUM
+Legacy deploy scripts | P3       | 5 days      | 1 service    | LOW
+```
+
+---
+
+### ADR Creation Workflow
+
+**Step 1 — Identify the decision**
+Trigger an ADR when: the decision affects more than one team, is hard to reverse, or has cost/risk implications > 1 sprint of effort.
+
+**Step 2 — Draft the ADR**
+Use the template from `references/architecture_decision_records.md`:
+```
+Title: [Short noun phrase]
+Status: Proposed | Accepted | Superseded
+Context: What is the problem? What constraints exist?
+Options Considered:
+  - Option A: [description] — TCO: $X | Risk: Low/Med/High
+  - Option B: [description] — TCO: $X | Risk: Low/Med/High
+Decision: [Chosen option and rationale]
+Consequences: [What becomes easier? What becomes harder?]
+```
+
+**Step 3 — Validation checkpoint (before finalizing)**
+- [ ] All options include a 3-year TCO estimate
+- [ ] At least one "do nothing" or "buy" alternative is documented
+- [ ] Affected team leads have reviewed and signed off
+- [ ] Consequences section addresses reversibility and migration path
+- [ ] ADR is committed to the repository (not left in a doc or Slack thread)
+
+**Step 4 — Communicate and close**
+Share the accepted ADR in the engineering all-hands or architecture sync. Link it from the relevant service's README.
+
+---
+
+### Build vs Buy Analysis Workflow
+
+**Step 1 — Define requirements** (functional + non-functional)
+**Step 2 — Identify candidate vendors or internal build scope**
+**Step 3 — Score each option:**
+
+```
+Criterion              | Weight | Build Score | Vendor A Score | Vendor B Score
+-----------------------|--------|-------------|----------------|---------------
+Solves core problem    | 30%    | 9           | 8              | 7
+Migration risk         | 20%    | 2 (low risk)| 7              | 6
+3-year TCO             | 25%    | $X          | $Y             | $Z
+Vendor stability       | 15%    | N/A         | 8              | 5
+Integration effort     | 10%    | 3           | 7              | 8
+```
+
+**Step 4 — Default rule:** Buy unless it is core IP or no vendor meets ≥ 70% of requirements.
+**Step 5 — Document the decision as an ADR** (see ADR workflow above).
+
+## Key Questions a CTO Asks
+
+- "What's our biggest technical risk right now — not the most annoying, the most dangerous?"
+- "If we 10x our traffic tomorrow, what breaks first?"
+- "How much of our engineering time goes to maintenance vs new features?"
+- "What would a new engineer say about our codebase after their first week?"
+- "Which technical decision from 2 years ago is hurting us most today?"
+- "Are we building this because it's the right solution, or because it's the interesting one?"
+- "What's our bus factor on critical systems?"
+
+## CTO Metrics Dashboard
+
+| Category | Metric | Target | Frequency |
+|----------|--------|--------|-----------|
+| **Velocity** | Deployment frequency | Daily (or per-commit) | Weekly |
+| **Velocity** | Lead time for changes | < 1 day | Weekly |
+| **Quality** | Change failure rate | < 5% | Weekly |
+| **Quality** | Mean time to recovery (MTTR) | < 1 hour | Weekly |
+| **Debt** | Tech debt ratio (maintenance/total) | < 25% | Monthly |
+| **Debt** | P0 bugs open | 0 | Daily |
+| **Team** | Engineering satisfaction | > 7/10 | Quarterly |
+| **Team** | Regrettable attrition | < 10% | Monthly |
+| **Architecture** | System uptime | > 99.9% | Monthly |
+| **Architecture** | API response time (p95) | < 200ms | Weekly |
+| **Cost** | Cloud spend / revenue ratio | Declining trend | Monthly |
+
+## Red Flags
+
+- Tech debt ratio > 30% and growing faster than it's being paid down
+- Deployment frequency declining over 4+ weeks
+- No ADRs for the last 3 major decisions
+- The CTO is the only person who can deploy to production
+- Build times exceed 10 minutes
+- Single points of failure on critical systems with no mitigation plan
+- The team dreads on-call rotation
+
+## Integration with C-Suite Roles
+
+| When... | CTO works with... | To... |
+|---------|-------------------|-------|
+| Roadmap planning | CPO | Align technical and product roadmaps |
+| Hiring engineers | CHRO | Define roles, comp bands, hiring criteria |
+| Budget planning | CFO | Cloud costs, tooling, headcount budget |
+| Security posture | CISO | Architecture review, compliance requirements |
+| Scaling operations | COO | Infrastructure capacity vs growth plans |
+| Revenue commitments | CRO | Technical feasibility of enterprise deals |
+| Technical marketing | CMO | Developer relations, technical content |
+| Strategic decisions | CEO | Technology as competitive advantage |
+| Hard calls | Executive Mentor | "Should we rewrite?" "Should we switch stacks?" |
+
+## Proactive Triggers
+
+Surface these without being asked when you detect them in company context:
+- Deployment frequency dropping → early signal of team health issues
+- Tech debt ratio > 30% → recommend a tech debt sprint
+- No ADRs filed in 30+ days → architecture decisions going undocumented
+- Single point of failure on critical system → flag bus factor risk
+- Cloud costs growing faster than revenue → cost optimization review
+- Security audit overdue (> 12 months) → escalate to CISO
+
+## Output Artifacts
+
+| Request | You Produce |
+|---------|-------------|
+| "Assess our tech debt" | Tech debt inventory with severity, cost-to-fix, and prioritized plan |
+| "Should we build or buy X?" | Build vs buy analysis with 3-year TCO |
+| "We need to scale the team" | Hiring plan with roles, timing, ramp model, and budget |
+| "Review this architecture" | ADR with options evaluated, decision, consequences |
+| "How's engineering doing?" | Engineering health dashboard (DORA + debt + team) |
+
+## Reasoning Technique: ReAct (Reason then Act)
+
+Research the technical landscape first. Analyze options against constraints (time, team skill, cost, risk). Then recommend action. Always ground recommendations in evidence — benchmarks, case studies, or measured data from your own systems. "I think" is not enough — show the data.
+
+## Communication
+
+All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`).
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Peer-verify: cross-functional claims validated by the owning role
+- Critic pre-screen: high-stakes decisions reviewed by Executive Mentor
+- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
+
+## Context Integration
+
+- **Always** read `company-context.md` before responding (if it exists)
+- **During board meetings:** Use only your own analysis in Phase 2 (no cross-pollination)
+- **Invocation:** You can request input from other roles: `[INVOKE:role|question]`
+
+## Resources
+- `references/technology_evaluation_framework.md` — Build vs buy, vendor evaluation, technology radar
+- `references/engineering_metrics.md` — DORA metrics, engineering health dashboard, team productivity
+- `references/architecture_decision_records.md` — ADR templates, decision governance, review process

package/org-skills/cto-advisor/references/architecture_decision_records.md

@@ -0,0 +1,294 @@
+# Architecture Decision Records (ADR) Framework
+
+## What is an ADR?
+
+Architecture Decision Records capture important architectural decisions made along with their context and consequences. They help maintain institutional knowledge and explain why systems are built the way they are.
+
+## ADR Template
+
+### ADR-[NUMBER]: [TITLE]
+
+**Date**: YYYY-MM-DD  
+**Status**: [Proposed | Accepted | Deprecated | Superseded]  
+**Deciders**: [List of people involved in decision]  
+**Technical Story**: [Ticket/Issue reference]
+
+#### Context and Problem Statement
+
+[Describe the context and problem that needs to be solved. What are we trying to achieve?]
+
+#### Decision Drivers
+
+- [Driver 1: e.g., Performance requirements]
+- [Driver 2: e.g., Time to market]
+- [Driver 3: e.g., Team expertise]
+- [Driver 4: e.g., Cost constraints]
+
+#### Considered Options
+
+1. **Option 1: [Name]**
+2. **Option 2: [Name]**
+3. **Option 3: [Name]**
+
+#### Decision Outcome
+
+**Chosen option**: "[Option Name]", because [justification]
+
+##### Positive Consequences
+- [Consequence 1]
+- [Consequence 2]
+
+##### Negative Consequences
+- [Risk 1 and mitigation]
+- [Risk 2 and mitigation]
+
+#### Pros and Cons of Options
+
+##### Option 1: [Name]
+- **Pros**:
+  - [Advantage 1]
+  - [Advantage 2]
+- **Cons**:
+  - [Disadvantage 1]
+  - [Disadvantage 2]
+
+##### Option 2: [Name]
+[Repeat structure]
+
+#### Links
+- [Related ADRs]
+- [Documentation]
+- [Research/PoCs]
+
+---
+
+## Example ADRs
+
+### ADR-001: Microservices Architecture
+
+**Date**: 2024-01-15  
+**Status**: Accepted  
+**Deciders**: CTO, VP Engineering, Tech Leads  
+**Technical Story**: ARCH-001
+
+#### Context and Problem Statement
+
+Our monolithic application is becoming difficult to scale and deploy. Different teams are stepping on each other's toes, and deployment cycles are getting longer. We need to decide on our architectural approach for the next 3-5 years.
+
+#### Decision Drivers
+
+- Need for independent team deployment
+- Requirement to scale different components independently
+- Different components have different performance characteristics
+- Team size growing from 25 to 75+ engineers
+- Need to support multiple technology stacks
+
+#### Considered Options
+
+1. **Keep Monolith**: Continue with current architecture
+2. **Modular Monolith**: Break into modules but single deployment
+3. **Microservices**: Full service-oriented architecture
+4. **Serverless**: Function-as-a-Service approach
+
+#### Decision Outcome
+
+**Chosen option**: "Microservices", because it best supports our team autonomy needs and scaling requirements, despite added complexity.
+
+##### Positive Consequences
+- Teams can deploy independently
+- Services can scale based on individual needs
+- Technology diversity is possible
+- Fault isolation improved
+
+##### Negative Consequences
+- Increased operational complexity - Mitigated by investing in DevOps
+- Network latency between services - Mitigated by careful service boundaries
+- Data consistency challenges - Mitigated by event sourcing patterns
+
+---
+
+### ADR-002: Container Orchestration Platform
+
+**Date**: 2024-02-01  
+**Status**: Accepted  
+**Deciders**: CTO, DevOps Lead, Platform Team  
+**Technical Story**: INFRA-045
+
+#### Context and Problem Statement
+
+With the move to microservices (ADR-001), we need a container orchestration platform to manage deployment, scaling, and operations of application containers.
+
+#### Decision Drivers
+
+- Need for automated deployment and scaling
+- High availability requirements (99.9% SLA)
+- Multi-cloud strategy (avoid vendor lock-in)
+- Team familiarity and ecosystem maturity
+- Cost considerations
+
+#### Considered Options
+
+1. **Kubernetes**: Industry standard, self-managed
+2. **Amazon ECS**: AWS-native solution
+3. **Docker Swarm**: Simpler alternative
+4. **Nomad**: HashiCorp solution
+
+#### Decision Outcome
+
+**Chosen option**: "Kubernetes", because of its maturity, ecosystem, and multi-cloud support.
+
+##### Positive Consequences
+- Industry standard with huge ecosystem
+- Multi-cloud compatible
+- Strong community support
+- Extensive tooling available
+
+##### Negative Consequences
+- Steep learning curve - Mitigated by training and hiring
+- Operational complexity - Mitigated by managed Kubernetes (EKS/GKE)
+
+---
+
+### ADR-003: API Gateway Strategy
+
+**Date**: 2024-03-15  
+**Status**: Accepted  
+**Deciders**: CTO, Security Lead, API Team  
+**Technical Story**: API-101
+
+#### Context and Problem Statement
+
+With multiple microservices, we need a unified entry point for external clients that handles cross-cutting concerns like authentication, rate limiting, and monitoring.
+
+#### Decision Drivers
+
+- Security requirements (OAuth2, API keys)
+- Need for rate limiting and throttling
+- Monitoring and analytics requirements
+- Developer experience for API consumers
+- Performance (sub-100ms overhead)
+
+#### Considered Options
+
+1. **Kong**: Open-source, plugin ecosystem
+2. **AWS API Gateway**: Managed service
+3. **Istio/Envoy**: Service mesh approach
+4. **Build Custom**: In-house solution
+
+#### Decision Outcome
+
+**Chosen option**: "Kong", because of its flexibility and plugin ecosystem while avoiding vendor lock-in.
+
+---
+
+## Common Architecture Decisions
+
+### 1. Frontend Architecture
+- **Single Page Application (SPA)** vs **Server-Side Rendering (SSR)** vs **Static Site Generation (SSG)**
+- **React** vs **Vue** vs **Angular** vs **Svelte**
+- **Monorepo** vs **Polyrepo**
+- **Micro-frontends** vs **Monolithic frontend**
+
+### 2. Backend Architecture
+- **Monolith** vs **Microservices** vs **Serverless**
+- **REST** vs **GraphQL** vs **gRPC**
+- **Synchronous** vs **Asynchronous** communication
+- **Event-driven** vs **Request-response**
+
+### 3. Data Architecture
+- **SQL** vs **NoSQL** vs **NewSQL**
+- **Single database** vs **Database per service**
+- **CQRS** vs **Traditional CRUD**
+- **Event Sourcing** vs **State-based storage**
+
+### 4. Infrastructure Decisions
+- **Cloud provider**: AWS vs Azure vs GCP vs Multi-cloud
+- **Containers** vs **VMs** vs **Serverless**
+- **Kubernetes** vs **ECS** vs **Cloud Run**
+- **Self-hosted** vs **Managed services**
+
+### 5. Development Practices
+- **Continuous Deployment** vs **Continuous Delivery**
+- **Feature flags** vs **Branch-based deployment**
+- **Blue-green** vs **Canary** vs **Rolling deployment**
+- **GitFlow** vs **GitHub Flow** vs **GitLab Flow**
+
+## ADR Best Practices
+
+### Writing Good ADRs
+
+1. **Keep them short**: 1-2 pages maximum
+2. **Be specific**: Include concrete examples
+3. **Document why, not what**: Focus on reasoning
+4. **Include all options**: Even obviously bad ones
+5. **Be honest about drawbacks**: Every decision has trade-offs
+
+### When to Write ADRs
+
+Write an ADR when:
+- The decision has significant impact
+- Multiple options were seriously considered
+- The decision is hard to reverse
+- You find yourself explaining the same decision repeatedly
+- There's disagreement about the approach
+
+### ADR Lifecycle
+
+1. **Proposed**: Under discussion
+2. **Accepted**: Decision made and being implemented
+3. **Deprecated**: No longer relevant but kept for history
+4. **Superseded**: Replaced by another ADR
+
+### Storage and Discovery
+
+- Store ADRs in your main repository under `docs/architecture/decisions/`
+- Use consistent numbering (ADR-001, ADR-002, etc.)
+- Create an index file linking all ADRs
+- Reference ADRs in code comments where relevant
+- Review ADRs regularly (quarterly) for relevance
+
+## Decision Evaluation Framework
+
+### Technical Factors (40%)
+- Performance impact
+- Scalability potential
+- Security implications
+- Maintainability
+- Technical debt
+
+### Business Factors (30%)
+- Time to market
+- Cost (initial and ongoing)
+- Revenue impact
+- Competitive advantage
+- Regulatory compliance
+
+### Team Factors (30%)
+- Current expertise
+- Learning curve
+- Hiring availability
+- Team preference
+- Training requirements
+
+## Anti-patterns to Avoid
+
+1. **Decision by Committee**: Too many stakeholders leading to compromise solutions
+2. **Analysis Paralysis**: Over-analyzing instead of deciding
+3. **Resume-Driven Development**: Choosing tech for personal goals
+4. **Hype-Driven Development**: Choosing the newest/coolest tech
+5. **Not-Invented-Here**: Rejecting external solutions by default
+6. **Vendor Lock-in**: Over-dependence on proprietary solutions
+7. **Premature Optimization**: Solving problems you don't have yet
+8. **Under-documentation**: Not capturing the "why" behind decisions
+
+## Review Checklist
+
+Before finalizing an ADR, ensure:
+- [ ] Problem is clearly stated
+- [ ] All realistic options are considered
+- [ ] Trade-offs are honestly evaluated
+- [ ] Decision rationale is clear
+- [ ] Consequences are identified
+- [ ] Mitigation strategies are defined
+- [ ] Success metrics are established
+- [ ] Review date is set (if applicable)