@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/skill-creator/workflows/create-domain-expertise-skill.md

@@ -0,0 +1,623 @@
+# Workflow: Create Exhaustive Domain Expertise Skill
+
+<objective>
+Build a comprehensive execution skill that does real work in a specific domain. Domain expertise skills are full-featured build skills with exhaustive domain knowledge in references, complete workflows for the full lifecycle (build → debug → optimize → ship), and can be both invoked directly by users AND loaded by other skills (like create-plans) for domain knowledge.
+</objective>
+
+<critical_distinction>
+**Regular skill:** "Do one specific task"
+**Domain expertise skill:** "Do EVERYTHING in this domain, with complete practitioner knowledge"
+
+Examples:
+
+- `expertise/macos-apps` - Build macOS apps from scratch through shipping
+- `expertise/python-games` - Build complete Python games with full game dev lifecycle
+- `expertise/rust-systems` - Build Rust systems programs with exhaustive systems knowledge
+- `expertise/web-scraping` - Build scrapers, handle all edge cases, deploy at scale
+
+Domain expertise skills:
+
+- ✅ Execute tasks (build, debug, optimize, ship)
+- ✅ Have comprehensive domain knowledge in references
+- ✅ Are invoked directly by users ("build a macOS app")
+- ✅ Can be loaded by other skills (create-plans reads references for planning)
+- ✅ Cover the FULL lifecycle, not just getting started
+</critical_distinction>
+
+<required_reading>
+**Read these reference files NOW:**
+
+1. references/recommended-structure.md
+2. references/core-principles.md
+3. references/skill-structure.md
+</required_reading>
+
+<process>
+## Step 1: Identify Domain
+
+Ask user what domain expertise to build:
+
+**Example domains:**
+
+- macOS/iOS app development
+- Python game development
+- Rust systems programming
+- Machine learning / AI
+- Web scraping and automation
+- Data engineering pipelines
+- Audio processing / DSP
+- 3D graphics / shaders
+- Unity/Unreal game development
+- Embedded systems
+
+Get specific: "Python games" or "Python games with Pygame specifically"?
+
+## Step 2: Confirm Target Location
+
+Explain:
+
+```
+Domain expertise skills go in: ~/.claude/skills/expertise/{domain-name}/
+
+These are comprehensive BUILD skills that:
+- Execute tasks (build, debug, optimize, ship)
+- Contain exhaustive domain knowledge
+- Can be invoked directly by users
+- Can be loaded by other skills for domain knowledge
+
+Name suggestion: {suggested-name}
+Location: ~/.claude/skills/expertise/{suggested-name}/
+```
+
+Confirm or adjust name.
+
+## Step 3: Identify Workflows
+
+Domain expertise skills cover the FULL lifecycle. Identify what workflows are needed.
+
+**Common workflows for most domains:**
+
+1. **build-new-{thing}.md** - Create from scratch
+2. **add-feature.md** - Extend existing {thing}
+3. **debug-{thing}.md** - Find and fix bugs
+4. **write-tests.md** - Test for correctness
+5. **optimize-performance.md** - Profile and speed up
+6. **ship-{thing}.md** - Deploy/distribute
+
+**Domain-specific workflows:**
+
+- Games: `implement-game-mechanic.md`, `add-audio.md`, `polish-ui.md`
+- Web apps: `setup-auth.md`, `add-api-endpoint.md`, `setup-database.md`
+- Systems: `optimize-memory.md`, `profile-cpu.md`, `cross-compile.md`
+
+Each workflow = one complete task type that users actually do.
+
+## Step 4: Exhaustive Research Phase
+
+**CRITICAL:** This research must be comprehensive, not superficial.
+
+### Research Strategy
+
+Run multiple web searches to ensure coverage:
+
+**Search 1: Current ecosystem**
+
+- "best {domain} libraries 2024 2025 2026"
+- "popular {domain} frameworks comparison"
+- "{domain} tech stack recommendations"
+
+**Search 2: Architecture patterns**
+
+- "{domain} architecture patterns"
+- "{domain} best practices design patterns"
+- "how to structure {domain} projects"
+
+**Search 3: Lifecycle and tooling**
+
+- "{domain} development workflow"
+- "{domain} testing debugging best practices"
+- "{domain} deployment distribution"
+
+**Search 4: Common pitfalls**
+
+- "{domain} common mistakes avoid"
+- "{domain} anti-patterns"
+- "what not to do {domain}"
+
+**Search 5: Real-world usage**
+
+- "{domain} production examples GitHub"
+- "{domain} case studies"
+- "successful {domain} projects"
+
+### Verification Requirements
+
+For EACH major library/tool/pattern found:
+
+- **Check recency:** When was it last updated?
+- **Check adoption:** Is it actively maintained? Community size?
+- **Check alternatives:** What else exists? When to use each?
+- **Check deprecation:** Is anything being replaced?
+
+**Red flags for outdated content:**
+
+- Articles from before 2023 (unless fundamental concepts)
+- Abandoned libraries (no commits in 12+ months)
+- Deprecated APIs or patterns
+- "This used to be popular but..."
+
+### Documentation Sources
+
+Use Context7 MCP when available:
+
+```
+mcp__context7__resolve-library-id: {library-name}
+mcp__context7__get-library-docs: {library-id}
+```
+
+Focus on official docs, not tutorials.
+
+## Step 5: Organize Knowledge Into Domain Areas
+
+Structure references by domain concerns, NOT by arbitrary categories.
+
+**For game development example:**
+
+```
+references/
+├── architecture.md         # ECS, component-based, state machines
+├── libraries.md           # Pygame, Arcade, Panda3D (when to use each)
+├── graphics-rendering.md  # 2D/3D rendering, sprites, shaders
+├── physics.md             # Collision, physics engines
+├── audio.md               # Sound effects, music, spatial audio
+├── input.md               # Keyboard, mouse, gamepad, touch
+├── ui-menus.md            # HUD, menus, dialogs
+├── game-loop.md           # Update/render loop, fixed timestep
+├── state-management.md    # Game states, scene management
+├── networking.md          # Multiplayer, client-server, P2P
+├── asset-pipeline.md      # Loading, caching, optimization
+├── testing-debugging.md   # Unit tests, profiling, debugging tools
+├── performance.md         # Optimization, profiling, benchmarking
+├── packaging.md           # Building executables, installers
+├── distribution.md        # Steam, itch.io, app stores
+└── anti-patterns.md       # Common mistakes, what NOT to do
+```
+
+**For macOS app development example:**
+
+```
+references/
+├── app-architecture.md     # State management, dependency injection
+├── swiftui-patterns.md     # Declarative UI patterns
+├── appkit-integration.md   # Using AppKit with SwiftUI
+├── concurrency-patterns.md # Async/await, actors, structured concurrency
+├── data-persistence.md     # Storage strategies
+├── networking.md           # URLSession, async networking
+├── system-apis.md          # macOS-specific frameworks
+├── testing-tdd.md          # Testing patterns
+├── testing-debugging.md    # Debugging tools and techniques
+├── performance.md          # Profiling, optimization
+├── design-system.md        # Platform conventions
+├── macos-polish.md         # Native feel, accessibility
+├── security-code-signing.md # Signing, notarization
+└── project-scaffolding.md  # CLI-based setup
+```
+
+**For each reference file:**
+
+- Markdown headings for structure (XML tags only as optional wrappers inside a section)
+- Decision trees: "If X, use Y. If Z, use A instead."
+- Comparison tables: Library vs Library (speed, features, learning curve)
+- Code examples showing patterns
+- "When to use" guidance
+- Platform-specific considerations
+- Current versions and compatibility
+
+## Step 6: Create SKILL.md
+
+Domain expertise skills use router pattern with essential principles:
+
+```yaml
+---
+name: build-{domain-name}
+description: Build {domain things} from scratch through shipping. Full lifecycle - build, debug, test, optimize, ship. {Any specific constraints like "CLI-only, no IDE"}.
+---
+
+# Build {Domain Name}
+
+## How {This Domain} Works
+
+{Domain-specific principles that ALWAYS apply}
+
+### 1. {First Principle}
+{Critical practice that can't be skipped}
+
+### 2. {Second Principle}
+{Another fundamental practice}
+
+### 3. {Third Principle}
+{Core workflow pattern}
+
+## Intake
+
+**Ask the user:**
+
+What would you like to do?
+1. Build a new {thing}
+2. Debug an existing {thing}
+3. Add a feature
+4. Write/run tests
+5. Optimize performance
+6. Ship/release
+7. Something else
+
+**Then read the matching workflow from `workflows/` and follow it.**
+
+## Routing
+
+| Response | Workflow |
+|----------|----------|
+| 1, "new", "create", "build", "start" | `workflows/build-new-{thing}.md` |
+| 2, "broken", "fix", "debug", "crash", "bug" | `workflows/debug-{thing}.md` |
+| 3, "add", "feature", "implement", "change" | `workflows/add-feature.md` |
+| 4, "test", "tests", "TDD", "coverage" | `workflows/write-tests.md` |
+| 5, "slow", "optimize", "performance", "fast" | `workflows/optimize-performance.md` |
+| 6, "ship", "release", "deploy", "publish" | `workflows/ship-{thing}.md` |
+| 7, other | Clarify, then select workflow or references |
+
+## After Every Change
+
+{Domain-specific verification steps}
+
+Example for compiled languages:
+```bash
+# 1. Does it build?
+{build command}
+
+# 2. Do tests pass?
+{test command}
+
+# 3. Does it run?
+{run command}
+```
+
+Report to the user:
+
+- "Build: ✓"
+- "Tests: X pass, Y fail"
+- "Ready for you to check [specific thing]"
+
+## Domain Knowledge
+
+All in `references/`:
+
+**Architecture:** {list files}
+**{Domain Area}:** {list files}
+**{Domain Area}:** {list files}
+**Development:** {list files}
+**Shipping:** {list files}
+
+## Workflows
+
+All in `workflows/`:
+
+| File | Purpose |
+|------|---------|
+| build-new-{thing}.md | Create new {thing} from scratch |
+| debug-{thing}.md | Find and fix bugs |
+| add-feature.md | Add to existing {thing} |
+| write-tests.md | Write and run tests |
+| optimize-performance.md | Profile and speed up |
+| ship-{thing}.md | Deploy/distribute |
+
+```
+
+## Step 7: Write Workflows
+
+For EACH workflow identified in Step 3:
+
+### Workflow Template
+
+```markdown
+# Workflow: {Workflow Name}
+
+## Required reading
+
+**Read these reference files NOW before {doing the task}:**
+1. references/{relevant-file}.md
+2. references/{another-relevant-file}.md
+3. references/{third-relevant-file}.md
+
+## Process
+
+### Step 1: {First Action}
+
+{What to do}
+
+### Step 2: {Second Action}
+
+{What to do - actual implementation steps}
+
+### Step 3: {Third Action}
+
+{What to do}
+
+### Step 4: Verify
+
+{How to prove it works}
+
+```bash
+{verification commands}
+```
+
+## Anti-patterns
+
+Avoid:
+
+- {Common mistake 1}
+- {Common mistake 2}
+- {Common mistake 3}
+
+## Success criteria
+
+A well-{completed task}:
+
+- {Criterion 1}
+- {Criterion 2}
+- {Criterion 3}
+- Builds/runs without errors
+- Tests pass
+- Feels {native/professional/correct}
+
+```
+
+**Key workflow characteristics:**
+- Starts with required_reading (which references to load)
+- Contains actual implementation steps (not just "read references")
+- Includes verification steps
+- Has success criteria
+- Documents anti-patterns
+
+## Step 8: Write Comprehensive References
+
+For EACH reference file identified in Step 5:
+
+### Structure Template
+
+Headings carry the structure; the `<option>`, `<pattern>`, and `<anti_pattern>` tags are optional wrappers that bound one block inside a section.
+
+````markdown
+# {Domain Area}
+
+Brief introduction to this domain area
+
+## Available Approaches/Libraries
+
+<option name="Library A">
+**When to use:** [specific scenarios]
+**Strengths:** [what it's best at]
+**Weaknesses:** [what it's not good for]
+**Current status:** v{version}, actively maintained
+**Learning curve:** [easy/medium/hard]
+
+```code
+# Example usage
+```
+
+</option>
+
+<option name="Library B">
+[Same structure]
+</option>
+
+## Choosing the Right Approach
+
+**If you need [X]:** Use [Library A]
+**If you need [Y]:** Use [Library B]
+**If you have [constraint Z]:** Use [Library C]
+
+**Avoid [Library D] if:** [specific scenarios]
+
+## Common Patterns
+
+<pattern name="Pattern Name">
+**Use when:** [scenario]
+**Implementation:** [code example]
+**Considerations:** [trade-offs]
+</pattern>
+
+## What NOT to Do
+
+<anti_pattern name="Common Mistake">
+**Problem:** [what people do wrong]
+**Why it's bad:** [consequences]
+**Instead:** [correct approach]
+</anti_pattern>
+
+## Platform-Specific Notes
+
+**Windows:** [considerations]
+**macOS:** [considerations]
+**Linux:** [considerations]
+**Mobile:** [if applicable]
+
+````
+
+### Quality Standards
+
+Each reference must include:
+- **Current information** (verify dates)
+- **Multiple options** (not just one library)
+- **Decision guidance** (when to use each)
+- **Real examples** (working code, not pseudocode)
+- **Trade-offs** (no silver bullets)
+- **Anti-patterns** (what NOT to do)
+
+### Common Reference Files
+
+Most domains need:
+- **architecture.md** - How to structure projects
+- **libraries.md** - Ecosystem overview with comparisons
+- **patterns.md** - Design patterns specific to domain
+- **testing-debugging.md** - How to verify correctness
+- **performance.md** - Optimization strategies
+- **deployment.md** - How to ship/distribute
+- **anti-patterns.md** - Common mistakes consolidated
+
+## Step 9: Validate Completeness
+
+### Completeness Checklist
+
+Ask: "Could a user build a professional {domain thing} from scratch through shipping using just this skill?"
+
+**Must answer YES to:**
+- [ ] All major libraries/frameworks covered?
+- [ ] All architectural approaches documented?
+- [ ] Complete lifecycle addressed (build → debug → test → optimize → ship)?
+- [ ] Platform-specific considerations included?
+- [ ] "When to use X vs Y" guidance provided?
+- [ ] Common pitfalls documented?
+- [ ] Current as of 2024-2026?
+- [ ] Workflows actually execute tasks (not just reference knowledge)?
+- [ ] Each workflow specifies which references to read?
+
+**Specific gaps to check:**
+- [ ] Testing strategy covered?
+- [ ] Debugging/profiling tools listed?
+- [ ] Deployment/distribution methods documented?
+- [ ] Performance optimization addressed?
+- [ ] Security considerations (if applicable)?
+- [ ] Asset/resource management (if applicable)?
+- [ ] Networking (if applicable)?
+
+### Dual-Purpose Test
+
+Test both use cases:
+
+**Direct invocation:** "Can a user invoke this skill and build something?"
+- Intake routes to appropriate workflow
+- Workflow loads relevant references
+- Workflow provides implementation steps
+- Success criteria are clear
+
+**Knowledge reference:** "Can create-plans load references to plan a project?"
+- References contain decision guidance
+- All options compared
+- Complete lifecycle covered
+- Architecture patterns documented
+
+## Step 10: Create Directory and Files
+
+```bash
+# Create structure
+mkdir -p ~/.claude/skills/expertise/{domain-name}
+mkdir -p ~/.claude/skills/expertise/{domain-name}/workflows
+mkdir -p ~/.claude/skills/expertise/{domain-name}/references
+
+# Write SKILL.md
+# Write all workflow files
+# Write all reference files
+
+# Verify structure
+ls -R ~/.claude/skills/expertise/{domain-name}
+```
+
+## Step 11: Document in create-plans
+
+Update `~/.claude/skills/create-plans/SKILL.md` to reference this new domain:
+
+Add to the domain inference table:
+
+```markdown
+| "{keyword}", "{domain term}" | expertise/{domain-name} |
+```
+
+So create-plans can auto-detect and offer to load it.
+
+## Step 12: Final Quality Check
+
+Review entire skill:
+
+**SKILL.md:**
+
+- [ ] Name matches directory (build-{domain-name})
+- [ ] Description explains it builds things from scratch through shipping
+- [ ] Essential principles inline (always loaded)
+- [ ] Intake asks what user wants to do
+- [ ] Routing maps to workflows
+- [ ] Reference index complete and organized
+- [ ] Workflows index complete
+
+**Workflows:**
+
+- [ ] Each workflow starts with required_reading
+- [ ] Each workflow has actual implementation steps
+- [ ] Each workflow has verification steps
+- [ ] Each workflow has success criteria
+- [ ] Workflows cover full lifecycle (build, debug, test, optimize, ship)
+
+**References:**
+
+- [ ] Structured with markdown headings (XML wrappers optional, inside a section)
+- [ ] Decision guidance in every file
+- [ ] Current versions verified
+- [ ] Code examples work
+- [ ] Anti-patterns documented
+- [ ] Platform considerations included
+
+**Completeness:**
+
+- [ ] A professional practitioner would find this comprehensive
+- [ ] No major libraries/patterns missing
+- [ ] Full lifecycle covered
+- [ ] Passes the "build from scratch through shipping" test
+- [ ] Can be invoked directly by users
+- [ ] Can be loaded by create-plans for knowledge
+
+</process>
+
+<success_criteria>
+Domain expertise skill is complete when:
+
+- [ ] Comprehensive research completed (5+ web searches)
+- [ ] All sources verified for recency (2024-2026)
+- [ ] Knowledge organized by domain areas (not arbitrary)
+- [ ] Essential principles in SKILL.md (always loaded)
+- [ ] Intake routes to appropriate workflows
+- [ ] Each workflow has required_reading + implementation steps + verification
+- [ ] Each reference has decision trees and comparisons
+- [ ] Anti-patterns documented throughout
+- [ ] Full lifecycle covered (build → debug → test → optimize → ship)
+- [ ] Platform-specific considerations included
+- [ ] Located in ~/.claude/skills/expertise/{domain-name}/
+- [ ] Referenced in create-plans domain inference table
+- [ ] Passes dual-purpose test: Can be invoked directly AND loaded for knowledge
+- [ ] User can build something professional from scratch through shipping
+</success_criteria>
+
+<anti_patterns>
+**DON'T:**
+
+- Copy tutorial content without verification
+- Include only "getting started" material
+- Skip the "when NOT to use" guidance
+- Forget to check if libraries are still maintained
+- Organize by document type instead of domain concerns
+- Make it knowledge-only with no execution workflows
+- Skip verification steps in workflows
+- Include outdated content from old blog posts
+- Skip decision trees and comparisons
+- Create workflows that just say "read the references"
+
+**DO:**
+
+- Verify everything is current
+- Include complete lifecycle (build → ship)
+- Provide decision guidance
+- Document anti-patterns
+- Make workflows execute real tasks
+- Start workflows with required_reading
+- Include verification in every workflow
+- Make it exhaustive, not minimal
+- Test both direct invocation and knowledge reference use cases
+</anti_patterns>