Initial commit

skills/core/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: core
+description: Core development principles and guidelines covering security, QA, performance, documentation, and coding standards. Used by all agents to ensure consistent quality across the Orchestra system.
+---
+
+# Core Development Skills
+
+This skill provides essential development principles and checklists that all Orchestra agents follow to maintain high-quality standards across security, testing, documentation, performance, and code quality.
+
+## Overview
+
+The core skills provide:
+- **Security principles** (security.yaml) - Secure coding practices and vulnerability prevention
+- **QA guidelines** (qa.yaml) - Testing standards and quality assurance procedures
+- **Release procedures** (release.yaml) - Deployment and release management
+- **Performance standards** (performance.yaml) - Optimization and efficiency guidelines
+- **Documentation standards** (documentation.yaml) - Technical writing and documentation best practices
+- **Coding standards** (coding-standards.yaml) - Code style and structure conventions
+- **Review checklist** (review-checklist.yaml) - Pre-merge code review requirements
+- **Clarification guidelines** (clarify.yaml) - Requirements clarification procedures
+- **Token efficiency** (token-efficiency.md) - Guidelines for minimizing token usage
+
+## When to Use
+
+Agents automatically reference these guidelines when:
+- **Iris** - Applies security.yaml for security audits
+- **Finn** - Uses qa.yaml and review-checklist.yaml for testing
+- **Eden** - Follows documentation.yaml for technical writing
+- **Kai** - References performance.yaml and coding-standards.yaml for architecture
+- **Blake** - Uses release.yaml for deployment coordination
+- **Riley** - Applies clarify.yaml for requirements clarification
+- **All agents** - Follow token-efficiency.md to optimize responses
+
+## Usage
+
+Agents can reference specific guidelines:
+
+```markdown
+See `skills/core/security.yaml` for security best practices
+See `skills/core/qa.yaml` for testing requirements
+See `skills/core/token-efficiency.md` for response optimization
+```
+
+## File Structure
+
+```
+skills/core/
+├── SKILL.md (this file)
+├── security.yaml          # Security principles
+├── qa.yaml                # QA and testing standards
+├── release.yaml           # Release management
+├── performance.yaml       # Performance optimization
+├── documentation.yaml     # Documentation standards
+├── coding-standards.yaml  # Code style conventions
+├── review-checklist.yaml  # Pre-merge checklist
+├── clarify.yaml           # Requirements clarification
+└── token-efficiency.md    # Token usage optimization
+```
+
+## Best Practices
+
+1. **Consistency** - All agents follow the same core principles
+2. **Reference, don't duplicate** - Agents link to guidelines rather than copying them
+3. **Update centrally** - Guidelines are maintained in one place
+4. **Agent-agnostic** - Principles apply across all specialized agents
+5. **Token efficient** - Guidelines are concise and focused
+
+## Integration
+
+These core skills are automatically available to all Orchestra agents. No explicit invocation is needed - agents reference them as part of their standard operating procedures.

skills/core/clarify.yaml

@@ -0,0 +1,14 @@
+name: clarify
+description: |
+  Skill for disambiguating unclear requests.
+  Used by Riley and Eden to ensure mutual understanding before work begins.
+principles:
+  - Never assume intent — verify.
+  - Confirm context, motivation, outcomes, and constraints.
+patterns:
+  - "Could you describe the current issue or goal more concretely?"
+  - "What would success look like for this task?"
+  - "Are there any specific risks, dependencies, or constraints?"
+usage_examples:
+  - A vague feature request without measurable goals.
+  - A conflict between business and technical priorities.

skills/core/coding-standards.yaml

@@ -0,0 +1,12 @@
+name: coding-standards
+description: |
+  Skill for ensuring all code follows project conventions and best practices.
+  Used by Skye, Kai, Leo, Mina, and Iris.
+principles:
+  - Code must be readable, consistent, and testable.
+  - Prefer explicitness over cleverness.
+  - Document assumptions inline when logic is non-trivial.
+checks:
+  - Lint and type checks pass (ESLint, mypy, etc.)
+  - Code includes comments for complex logic.
+  - Sensitive data is never logged or exposed.

skills/core/documentation.yaml

@@ -0,0 +1,12 @@
+name: documentation
+description: |
+  Skill for maintaining clear and consistent documentation.
+  Used by Eden and Kai.
+principles:
+  - Documentation must tell the "why" as well as the "how".
+  - Every feature or change must include updated docs or ADR references.
+formats:
+  - README.md
+  - CHANGELOG.md
+  - ADR (Architecture Decision Record)
+  - Runbook

skills/core/performance.yaml

@@ -0,0 +1,11 @@
+name: performance
+description: |
+  Skill for diagnosing and improving runtime performance.
+  Used by Nova, Leo, and Finn.
+principles:
+  - Measure before optimizing.
+  - Define target metrics explicitly.
+metrics:
+  - Time to First Byte (TTFB)
+  - Core Web Vitals (LCP, CLS, FID)
+  - API latency budgets

skills/core/qa.yaml

@@ -0,0 +1,12 @@
+name: qa
+description: |
+  Skill for designing and executing automated quality assurance processes.
+  Used by Finn.
+principles:
+  - Focus testing on risk areas and user flows.
+  - Prioritize fast feedback (CI-first testing).
+checklist:
+  - [ ] Unit tests for critical logic
+  - [ ] Integration tests for data flow
+  - [ ] E2E tests for user-facing functionality
+  - [ ] Regression tests before release

skills/core/release.yaml

@@ -0,0 +1,11 @@
+name: release
+description: |
+  Skill governing safe deployment and version management.
+  Used by Blake.
+principles:
+  - Each release must be reversible.
+  - Document every change and communicate clearly.
+steps:
+  - Tag version and update changelog
+  - Run smoke/E2E tests post-deploy
+  - Announce deployment status

skills/core/review-checklist.yaml

@@ -0,0 +1,12 @@
+name: review-checklist
+description: |
+  Skill for systematic review before merging code.
+  Used by Skye, Finn, and Iris.
+principles:
+  - Reviews should focus on correctness, clarity, and maintainability.
+  - Do not approve PRs with missing documentation or untested code.
+checklist:
+  - [ ] All tests pass and coverage is >80%
+  - [ ] Naming and structure follow project conventions
+  - [ ] Security-sensitive code reviewed by Iris
+  - [ ] Docs and changelogs updated

skills/core/security.yaml

@@ -0,0 +1,13 @@
+name: security
+description: |
+  Skill enforcing secure practices throughout development.
+  Used by Iris, Mina, and Leo.
+principles:
+  - Least privilege, defense in depth.
+  - Secrets never hard-coded or logged.
+  - Dependencies regularly scanned and updated.
+checklist:
+  - [ ] No hardcoded credentials or tokens
+  - [ ] SBOM generated and verified
+  - [ ] OAuth scopes minimized
+  - [ ] Policies reviewed before merge

skills/core/token-efficiency.md

@@ -0,0 +1,193 @@
+# Token Efficiency Skill
+
+**Purpose**: Minimize unnecessary token usage while maintaining code quality and thoroughness.
+
+## Core Principles
+
+### 1. Targeted Search, Not Exploration
+
+**Always prefer specific over general:**
+- ✅ `Glob("**/auth/login.ts")` - Exact file
+- ✅ `Grep("function handleAuth", type="ts")` - Specific pattern with file type
+- ❌ `Glob("**/*.ts")` - Too broad
+- ❌ Reading entire directories without filtering
+
+### 2. Read Only What You Need
+
+**Before reading a file, ask:**
+- Do I need the entire file, or just specific sections?
+- Can I use grep to find the relevant parts first?
+- Has this file already been read in the conversation?
+
+**Use Read with limits:**
+```
+Read(file_path, offset=100, limit=50)  # Only read 50 lines starting at line 100
+```
+
+### 3. Search Hierarchy (Most to Least Efficient)
+
+1. **Known location**: Direct file read if path is known
+2. **Pattern matching**: Glob with specific patterns
+3. **Keyword search**: Grep for specific terms
+4. **Contextual search**: Grep with -A/-B flags for context
+5. **Agent search**: Task tool with Explore agent (last resort)
+
+### 4. Incremental Discovery
+
+**Don't gather everything upfront:**
+```
+Bad approach:
+1. Read all files in src/
+2. Read all test files
+3. Read all config files
+4. Then start implementation
+
+Good approach:
+1. Read the specific file to modify
+2. Implement the change
+3. Only read related files if needed during implementation
+4. Read tests only when writing test updates
+```
+
+### 5. Scope Boundaries
+
+**Set clear limits:**
+- Maximum files to examine: 5-10 for most tasks
+- Maximum file size to read fully: ~500 lines
+- Large files: Use offset/limit or grep first
+- Stop once you have sufficient information
+
+### 6. Efficient Grep Usage
+
+**Use appropriate output modes:**
+- `files_with_matches`: Just need to know if pattern exists
+- `count`: Just need to know how many matches
+- `content`: Need to see actual matches (use head_limit)
+
+**Add context only when needed:**
+```
+Grep("error handler", output_mode="content", -C=3, head_limit=10)
+# Only 10 results with 3 lines of context each
+```
+
+### 7. Avoid Redundant Operations
+
+**Check conversation history first:**
+- Don't re-read files already examined
+- Reference previous findings instead of re-searching
+- Build on existing knowledge
+
+### 8. Model Selection for Task Tool
+
+**Choose the right model for the job:**
+```
+# Simple, well-defined task
+Task(description="...", model="haiku", prompt="...")
+
+# Default for most tasks (good balance)
+Task(description="...", model="sonnet", prompt="...")
+
+# Complex reasoning required (use sparingly)
+Task(description="...", model="opus", prompt="...")
+```
+
+## Practical Examples
+
+### Example 1: Adding a New Function
+
+**Inefficient approach:**
+```
+1. Read entire src/ directory
+2. Read all related files
+3. Search for all similar patterns
+4. Then implement
+```
+
+**Efficient approach:**
+```
+1. Grep for similar function names (files_with_matches)
+2. Read ONE example file
+3. Implement based on that pattern
+4. Only read more if the first example is unclear
+```
+
+### Example 2: Bug Investigation
+
+**Inefficient approach:**
+```
+1. Read all files that might be related
+2. Search entire codebase for error messages
+3. Check all test files
+```
+
+**Efficient approach:**
+```
+1. Grep for the specific error message
+2. Read only the files containing that error
+3. Check git blame if needed to understand context
+4. Read tests only for files being modified
+```
+
+### Example 3: Code Review
+
+**Inefficient approach:**
+```
+1. Read all files in the PR
+2. Read all related test files
+3. Read all documentation
+4. Then provide feedback
+```
+
+**Efficient approach:**
+```
+1. Use git diff to see only changed lines
+2. Read changed files with offset/limit to focus on modifications
+3. Grep for test coverage of changed functions
+4. Request summaries instead of reading full docs
+```
+
+## Token Budget Estimates
+
+**Quick reference for delegation:**
+
+| Task Type | Estimated Tokens | Recommended Model |
+|-----------|------------------|-------------------|
+| Simple bug fix | 2-5K | haiku |
+| New feature (small) | 5-10K | haiku |
+| New feature (medium) | 10-20K | sonnet |
+| Architecture design | 20-30K | sonnet |
+| Complex refactoring | 30-50K | sonnet |
+| Full system review | Split into chunks | sonnet |
+
+## Red Flags (Stop and Optimize)
+
+**If you find yourself:**
+- Reading more than 10 files for a single task
+- Using Glob with `**/*` without file type filtering
+- Reading entire large files (>1000 lines) without specific need
+- Re-reading files already examined in the conversation
+- Exploring code "just to understand better" without clear need
+
+**Then:** Stop and refine your approach. Ask yourself:
+1. What specific information do I need?
+2. What's the minimum search required to get it?
+3. Can I infer this from what I already know?
+
+## Integration with Other Skills
+
+This skill should be applied in conjunction with:
+- **code-quality.md**: Maintain quality while being efficient
+- **testing.md**: Test only what's necessary, focus on critical paths
+- **security.md**: Targeted security checks, not exhaustive scans
+- **documentation.md**: Document changes, not entire codebase
+
+## Success Metrics
+
+**You're doing it right when:**
+- Tasks complete in <20K tokens for most features
+- You find what you need in 1-3 search operations
+- You reference previous reads instead of re-reading
+- You can justify every file you read
+- Subagents return focused, relevant results
+
+**Review and improve** if token usage is consistently high without proportional complexity in the task.