Brain/SKILL-RECOMMENDATIONS.md

# Skill Recommendations for TekDek Development Team

**Date**: 2026-04-13  
**Prepared by**: ParzivalTD  
**For**: Glytcht's Review

---

## Overview

Each agent needs both **standard tools** (to do their job) and **custom skills** (to excel in their domain).

Standard tools are self-explanatory. Custom skills are the force multipliers.

---

## DAEDALUS — Chief Architect

### Essential Standard Tools/Access
- [ ] **High thinking budget** — Deep architectural work requires reflection (budget: high)
- [ ] **Documentation tools** — Can write/edit specifications (markdown, google docs)
- [ ] **Diagramming capability** — ASCII diagrams, flowcharts, decision trees
- [ ] **Memory/context enabled** — Must track architectural decisions over time (context: 150k+)
- [ ] **Read-only access** to: Git repos, past architecture decisions, existing codebase
- [ ] **Write access** to: Architecture specification repository, design documents

### Recommended Custom Skills

**1. ADR Generator** (Architecture Decision Records)
- **Purpose**: Automatically capture architectural decisions with reasoning
- **Functionality**: Takes a decision → generates ADR with context, alternatives, rationale, consequences
- **Benefit**: Builds decision history automatically, prevents architectural drift
- **Example**: Daedalus decides "Use PostgreSQL instead of MySQL" → skill generates formatted ADR

**2. System Diagram Creator**
- **Purpose**: Generate system architecture diagrams from specifications
- **Functionality**: ASCII diagrams, component relationships, data flow visualization
- **Benefit**: Specs become visual, easier for team to understand
- **Example**: Daedalus writes schema → skill generates entity-relationship diagram

**3. Scalability Analyzer**
- **Purpose**: Analyze designs for scalability bottlenecks
- **Functionality**: Questions design assumptions, identifies breaking points, suggests optimizations
- **Benefit**: Catch scaling issues early before implementation
- **Example**: "This design handles 1000 users. At 10,000 users, this table will have 1B rows. Suggest: sharding strategy"

**4. Trade-off Documenter**
- **Purpose**: Automatically capture design trade-offs
- **Functionality**: For each decision, record: chosen approach, rejected alternatives, why
- **Benefit**: Future architects understand why decisions were made
- **Example**: "Chose REST over GraphQL because: simpler for team, fewer queries, caching easier"

### Model Recommendation
- **Current**: Claude Opus 4.6 ✅ (right choice for deep thinking)
- **Keep**: Opus for architectural work

---

## TALOS — Technical Coder

### Essential Standard Tools/Access
- [ ] **Git access** — Read/write to all dev branches, code review capability
- [ ] **PHP 8.2+ environment** — Full development setup, Composer
- [ ] **MySQL 8.0+ environment** — Database design, migrations, optimization
- [ ] **PHPUnit testing framework** — Unit tests, integration tests
- [ ] **Code quality tools** — Linting (PHPStan, PHP_CodeSniffer), formatting
- [ ] **Performance profiling** — Query profiling, memory analysis
- [ ] **Medium context budget** — 120k-150k tokens (focused but thorough)

### Recommended Custom Skills

**1. PHP Code Optimizer**
- **Purpose**: Analyze PHP code for performance bottlenecks
- **Functionality**: Identifies slow patterns, suggests optimizations, refactors inefficient code
- **Benefit**: Reduces performance issues before they reach production
- **Example**: Detects N+1 queries, suggests eager loading; spots unoptimized loops

**2. Database Schema Analyzer**
- **Purpose**: Analyze schema design for indexing, normalization, performance
- **Functionality**: Suggests missing indexes, flags denormalization opportunities, analyzes cardinality
- **Benefit**: Database performs well at scale
- **Example**: "Add index on (persona_id, status) for 100x faster list queries"

**3. API Contract Generator**
- **Purpose**: Generate OpenAPI/Swagger specs directly from code
- **Functionality**: Reads implementation → generates comprehensive API documentation
- **Benefit**: API docs always match actual implementation
- **Example**: Reads controller → generates OpenAPI spec with examples, error codes

**4. Test Coverage Analyzer**
- **Purpose**: Analyze test coverage, identify untested code paths
- **Functionality**: Generates coverage reports, suggests critical paths needing tests, flags risky code
- **Benefit**: High confidence in code quality, catch bugs early
- **Example**: "Functions X and Y are untested. Add tests for edge cases: null input, empty array, max int"

**5. Migration Validator**
- **Purpose**: Validate database migrations for safety and reversibility
- **Functionality**: Checks for irreversible ops, suggests rollback strategies, verifies correctness
- **Benefit**: Deployments that can be safely rolled back
- **Example**: "This migration drops a column. Add a `down()` to recreate it. Consider: backup first?"

### Model Recommendation
- **Current**: Claude Sonnet 4.6 ✅ (good balance of speed/quality)
- **Consider**: Could use Opus for complex optimization work, but Sonnet is fine for day-to-day

---

## ICARUS — Frontend Designer

### Essential Standard Tools/Access
- [ ] **Git access** — Read/write to UI code branches
- [ ] **HTML5/CSS3/JavaScript sandbox** — Full development environment
- [ ] **Browser dev tools access** — DevTools, Lighthouse, responsive testing
- [ ] **Accessibility testing** — WAVE, axe, manual WCAG testing
- [ ] **Design tool access** — Figma, Sketch, or equivalent (if used)
- [ ] **Performance profiling** — Lighthouse, Web Vitals, bundle analysis
- [ ] **Fast context** — Lower token budget OK (40k-60k), prioritize speed for iteration

### Recommended Custom Skills

**1. Responsive Design Tester**
- **Purpose**: Test designs across all breakpoints and devices
- **Functionality**: Generates responsive test matrix (320, 375, 768, 1024, 1920+), identifies layout issues
- **Benefit**: Catch responsive issues early, ensure mobile/tablet/desktop all work
- **Example**: "Screen 320px: button wraps awkwardly. Suggest: reduce padding or stack vertically"

**2. Accessibility Auditor**
- **Purpose**: Automated accessibility compliance checking
- **Functionality**: WCAG 2.1 AA analysis, color contrast verification, keyboard navigation testing, semantic HTML checking
- **Benefit**: Catch accessibility issues before QA, ensure inclusive design
- **Example**: "Missing alt text on 3 images. Input lacks label. Color contrast 3.2:1 (need 4.5:1 for AA)"

**3. Performance Optimizer**
- **Purpose**: Analyze UI performance, suggest optimizations
- **Functionality**: Lighthouse audit, bundle analysis, image optimization, CSS/JS minification suggestions
- **Benefit**: Fast UI = happy users
- **Example**: "Lighthouse score 72 → 95 by: lazy-loading images (10KB saved), removing unused CSS (8KB)"

**4. Design System Validator**
- **Purpose**: Ensure UI components follow design system/brand guidelines
- **Functionality**: Checks colors, typography, spacing, component patterns against standards
- **Benefit**: Consistent design across all UIs
- **Example**: "Button uses #2563EB, should be #3B82F6 per brand. Heading font-size 24px, should be 20px"

**5. Interaction Pattern Suggester**
- **Purpose**: Suggest interaction patterns based on component type and context
- **Functionality**: Recommends animations, hover states, error messages, loading states
- **Benefit**: UI feels polished and professional
- **Example**: "Form submit should show loading spinner. Button color should change on hover. Consider skeleton loading during fetch."

### Model Recommendation
- **Current**: Claude Haiku 4.5 ✅ (fast, good for rapid iteration)
- **Keep**: Haiku for speed; can escalate to Sonnet if design questions need depth

---

## HEPHAESTUS — Operations & Infrastructure

### Essential Standard Tools/Access
- [ ] **Git access** — Read all branches, write to deployment branches
- [ ] **SSH/Server access** — Direct access to web.tekdek.dev, database servers
- [ ] **Docker/Container tools** — Orchestration, container management, image management
- [ ] **Database tools** — MySQL client, backup/restore, migration tools
- [ ] **Monitoring/Observability** — Log aggregation, metrics, alerting (can be integrated)
- [ ] **Incident management** — Runbooks, playbooks, status dashboard
- [ ] **Medium context budget** — 100k-150k tokens (focused on operational clarity)

### Recommended Custom Skills

**1. Deployment Orchestrator**
- **Purpose**: Automate safe, tested deployments with rollback capability
- **Functionality**: Pre-deployment validation, automated testing, deployment staging, health checks, automatic rollback if fail
- **Benefit**: Deployments are fast, safe, and can be rolled back instantly
- **Example**: "Deploy requested. Running tests... All pass. Staging deploy... Health check OK. Prod deploy complete. Monitoring active for 5 min."

**2. Infrastructure Health Monitor**
- **Purpose**: Continuous monitoring with intelligent alerting
- **Functionality**: Tracks uptime, CPU, memory, disk, database performance, response times; intelligent alerts (ignore spikes, catch trends)
- **Benefit**: Catch issues before they become outages
- **Example**: "CPU trending upward (40% → 60% over 2h). Investigate before it hits 80%. DB query time slow on user query."

**3. Backup & Disaster Recovery Automator**
- **Purpose**: Automate backups, verify integrity, test recovery procedures
- **Functionality**: Daily backups, weekly integrity checks, monthly full recovery test, generates recovery documentation
- **Benefit**: Confidence that backups work when needed
- **Example**: "Daily backup complete (2.3 GB). Weekly integrity check: PASS. Last full recovery test: 2026-04-06 (OK)"

**4. Incident Response Conductor**
- **Purpose**: Guide incident response with playbooks
- **Functionality**: Identifies issue type, suggests playbook, assists with debugging, coordinates response, generates post-mortem
- **Benefit**: Faster incident resolution, consistent responses, captured learnings
- **Example**: "Database down detected. Running 'Database Recovery' playbook. Step 1: Check connection... FAIL. Step 2: Check replication..."

**5. Infrastructure Capacity Planner**
- **Purpose**: Predict when infrastructure needs to scale
- **Functionality**: Analyzes growth trends, projects when resources hit limits, recommends scaling strategy
- **Benefit**: Scale proactively before problems occur
- **Example**: "DB at 60% capacity. Growth rate: 5%/month. Will hit 80% in 4 months. Recommend: increase storage Feb 2026, or implement sharding"

### Model Recommendation
- **Current**: Claude Sonnet 4.6 ✅ (good balance for operational decision-making)
- **Keep**: Sonnet for consistency with dev work

---

## Summary Table

| Agent | Model | Standard Tools | # Custom Skills | Priority Skills |
|-------|-------|---|---|---|
| **Daedalus** | Opus 4.6 | Docs, Diagramming, High context | 4 | ADR Generator, Scale Analyzer |
| **Talos** | Sonnet 4.6 | Git, PHP/MySQL, PHPUnit, Medium context | 5 | Code Optimizer, Schema Analyzer, API Generator |
| **Icarus** | Haiku 4.5 | Git, HTML/CSS/JS, Lighthouse, Low context | 5 | Accessibility Auditor, Responsive Tester, Perf Optimizer |
| **Hephaestus** | Sonnet 4.6 | Git, SSH, Docker, Monitoring, Medium context | 5 | Deployment Orchestrator, Health Monitor, Backup Automator |

---

## Implementation Priority

### Phase 1 (Essential — Deploy Day 1)
- Standard tools for all agents
- Models locked in
- Git/SSH access configured

### Phase 2 (High Impact — Deploy Week 1)
- Daedalus: ADR Generator + Scale Analyzer
- Talos: Code Optimizer + API Generator
- Icarus: Accessibility Auditor + Responsive Tester
- Hephaestus: Deployment Orchestrator + Health Monitor

### Phase 3 (Nice to Have — Deploy Week 2-3)
- All remaining custom skills
- Integrate with monitoring/logging systems
- Optimize based on initial feedback

---

## Custom Skill Development Notes

### Building Custom Skills
These custom skills could be:
- **OpenClaw Skills** (if we build them as reusable skills)
- **Agent-specific prompts** (simpler, embedded in agent system prompt)
- **Integration with existing tools** (Lighthouse plugin, PHPStan wrapper, etc.)

**Recommendation**: Start with agent-specific prompts (built into system prompt), then graduate to OpenClaw Skills if they prove valuable.

### Examples of Skill Prompts

**For Talos** (Code Optimizer prompt snippet):
```
When reviewing PHP code, analyze for:
- N+1 query patterns (suggest eager loading)
- Unoptimized loops (suggest collection methods)
- Missing indexes (suggest database optimization)
- Object allocation in loops (refactor out)
Report findings as: [Issue] → [Why it matters] → [Suggested fix]
```

**For Icarus** (Accessibility Auditor snippet):
```
When building UI, verify:
- All images have alt text
- All inputs have associated labels
- Color contrast ≥ 4.5:1 for AA compliance
- Keyboard navigation works
- Semantic HTML (no div soup)
Report: [Issue] → [WCAG criterion] → [How to fix]
```

---

## Questions for You

1. **Custom Skills**: Should I build these as OpenClaw Skills or embed them in agent prompts?
2. **Priority**: Approve all 4 high-impact skills for Phase 2, or be more selective?
3. **Monitoring**: Should Hephaestus integrate with existing monitoring systems (DataDog, etc.) or use manual checks?
4. **Accessibility**: Is WCAG 2.1 AA the right standard for Icarus, or should we aim for AAA?

---

## Recommendation

**Deploy**:
- ✅ All standard tools (access established, models locked)
- ✅ Daedalus: ADR Generator + Scale Analyzer (architectural excellence)
- ✅ Talos: Code Optimizer + API Generator (dev velocity)
- ✅ Icarus: Accessibility Auditor + Responsive Tester (quality + inclusion)
- ✅ Hephaestus: Deployment Orchestrator + Health Monitor (reliability)

**This gives each agent 2 force multipliers immediately while keeping setup manageable.**

---

**Ready to implement upon your approval.**