@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/skills/debug-like-expert/references/when-to-research.md

@@ -0,0 +1,361 @@
+
+<overview>
+Debugging requires both reasoning about code and researching external knowledge. The skill is knowing when to use each. This guide helps you recognize signals that indicate you need external knowledge vs when you can reason through the problem with the code in front of you.
+</overview>
+
+
+<research_signals>
+
+**1. Error messages you don't recognize**
+- Stack traces from libraries you haven't used
+- Cryptic system errors
+- Framework-specific error codes
+
+**Action**: Web search the exact error message in quotes
+- Often leads to GitHub issues, Stack Overflow, or official docs
+- Others have likely encountered this
+
+<example>
+Error: `EADDRINUSE: address already in use :::3000`
+
+This is a system-level error. Research it:
+- Web search: "EADDRINUSE address already in use"
+- Learn: Port is already occupied by another process
+- Solution: Find and kill the process, or use different port
+</example>
+
+**2. Library/framework behavior doesn't match expectations**
+- You're using a library correctly (you think) but it's not working
+- Documentation seems to contradict behavior
+- Version-specific quirks
+
+**Action**: Check official documentation and recent issues
+- Use Context7 MCP for library docs
+- Search GitHub issues for the library
+- Check if there are breaking changes in recent versions
+
+<example>
+You're using `useEffect` in React but it's running on every render despite empty dependency array.
+
+Research needed:
+- Check React docs for useEffect rules
+- Search: "useEffect running on every render"
+- Discover: React 18 StrictMode runs effects twice in dev mode
+</example>
+
+**3. Domain knowledge gaps**
+- Debugging authentication: need to understand OAuth flow
+- Debugging database: need to understand indexes, query optimization
+- Debugging networking: need to understand HTTP caching, CORS
+
+**Action**: Research the domain concept, not just the specific bug
+- Use MCP servers for domain knowledge
+- Read official specifications
+- Find authoritative guides
+
+**4. Platform-specific behavior**
+- "Works in Chrome but not Safari"
+- "Works on Mac but not Windows"
+- "Works in Node 16 but not Node 18"
+
+**Action**: Research platform differences
+- Browser compatibility tables
+- Platform-specific documentation
+- Known platform bugs
+
+**5. Recent changes in ecosystem**
+- Package update broke something
+- New framework version behaves differently
+- Deprecated API
+
+**Action**: Check changelogs and migration guides
+- Library CHANGELOG.md
+- Migration guides
+- "Breaking changes" documentation
+
+</research_signals>
+
+
+<reasoning_signals>
+
+**1. The bug is in YOUR code**
+- Not library behavior, not system issues
+- Your business logic, your data structures
+- Code you or your team wrote
+
+**Approach**: Read the code, trace execution, add logging
+- You have full access to the code
+- You can modify it to add observability
+- No external documentation will help
+
+<example>
+Bug: Shopping cart total calculates incorrectly
+
+This is your logic:
+```javascript
+function calculateTotal(items) {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+```
+
+Don't research "shopping cart calculation bugs"
+DO reason through it:
+- Log each item's price and quantity
+- Log the running sum
+- Trace the logic step by step
+</example>
+
+**2. You have all the information needed**
+- The bug is reproducible
+- You can read all relevant code
+- No external dependencies involved
+
+**Approach**: Use investigation techniques
+- Binary search to narrow down
+- Minimal reproduction
+- Working backwards
+- Add observability
+
+**3. It's a logic error, not a knowledge gap**
+- Off-by-one errors
+- Wrong conditional
+- State management issue
+- Data transformation bug
+
+**Approach**: Trace the logic carefully
+- Print intermediate values
+- Check assumptions
+- Verify each step
+
+**4. The answer is in the behavior, not the documentation**
+- "What is this function actually doing?"
+- "Why is this value null?"
+- "When does this code execute?"
+
+**Approach**: Observe the actual behavior
+- Add logging
+- Use a debugger
+- Test with different inputs
+
+</reasoning_signals>
+
+
+<research_how>
+
+**Web Search - When and How**
+
+**When**:
+- Error messages
+- Library-specific questions
+- "How to X in framework Y"
+- Troubleshooting platform issues
+
+**How**:
+- Use exact error messages in quotes: `"Cannot read property 'map' of undefined"`
+- Include framework/library version: `"react 18 useEffect behavior"`
+- Add "github issue" for known bugs: `"prisma connection pool github issue"`
+- Add year for recent changes: `"nextjs 14 middleware 2024"`
+
+**Good search queries**:
+- `"ECONNREFUSED" node.js postgres`
+- `"Maximum update depth exceeded" react hooks`
+- `typescript generic constraints examples`
+
+**Bad search queries**:
+- `my code doesn't work` (too vague)
+- `bug in react` (too broad)
+- `help` (useless)
+
+**Context7 MCP - When and How**
+
+**When**:
+- Need API reference
+- Understanding library concepts
+- Finding specific function signatures
+- Learning correct usage patterns
+
+**How**:
+```
+Use mcp__context7__resolve-library-id with library name
+Then mcp__context7__get-library-docs with library ID
+Ask specific questions about the library
+```
+
+**Good uses**:
+- "How do I use Prisma transactions?"
+- "What are the parameters for stripe.customers.create?"
+- "How does Express middleware error handling work?"
+
+**Bad uses**:
+- "Fix my bug" (too vague, Context7 provides docs not debugging)
+- "Why isn't my code working?" (need to research specific concepts, not general debugging)
+
+**GitHub Issues Search**
+
+**When**:
+- Experiencing behavior that seems like a bug
+- Library not working as documented
+- Looking for workarounds
+
+**How**:
+- Search in the library's GitHub repo
+- Include relevant keywords
+- Check both open and closed issues
+- Look for issues with "bug" or "regression" labels
+
+**Official Documentation**
+
+**When**:
+- Learning how something should work
+- Checking if you're using API correctly
+- Understanding configuration options
+- Finding migration guides
+
+**How**:
+- Start with official docs, not blog posts
+- Check version-specific docs
+- Read examples and guides, not just API reference
+- Look for "Common Pitfalls" or "Troubleshooting" sections
+
+</research_how>
+
+
+<balance>
+
+**The research trap**: Spending hours reading docs about topics tangential to your bug
+- You think it's a caching issue, so you read all about cache invalidation
+- But the actual bug is a typo in a variable name
+
+**The reasoning trap**: Spending hours reading code when the answer is well-documented
+- You're debugging why auth doesn't work
+- The docs clearly explain the setup you missed
+- You could have found it in 5 minutes of reading
+
+**The balance**:
+
+1. **Start with quick research** (5-10 minutes)
+   - Search the error message
+   - Check official docs for the feature you're using
+   - Skim recent issues
+
+2. **If research doesn't yield answers, switch to reasoning**
+   - Add logging
+   - Trace execution
+   - Form hypotheses
+
+3. **If reasoning reveals knowledge gaps, research those specific gaps**
+   - "I need to understand how WebSocket reconnection works"
+   - "I need to know if this library supports transactions"
+
+4. **Alternate as needed**
+   - Research → reveals what to investigate
+   - Reasoning → reveals what to research
+   - Keep switching based on what you learn
+
+<example>
+**Bug**: Real-time updates stop working after 1 hour
+
+**Start with research** (5 min):
+- Search: "websocket connection drops after 1 hour"
+- Find: Common issue with load balancers having connection timeouts
+
+**Switch to reasoning**:
+- Check if you're using a load balancer: YES
+- Check load balancer timeout setting: 3600 seconds (1 hour)
+- Hypothesis: Load balancer is killing the connection
+
+**Quick research**:
+- Search: "websocket load balancer timeout fix"
+- Find: Implement heartbeat/ping to keep connection alive
+
+**Reasoning**:
+- Check if library supports heartbeat: YES
+- Implement ping every 30 seconds
+- Test: Connection stays alive for 3+ hours
+
+**Total time**: 20 minutes (research: 10 min, reasoning: 10 min)
+**Success**: Found and fixed the issue
+
+vs
+
+**Wrong approach**: Spend 2 hours reading WebSocket spec
+- Learned a lot about WebSocket protocol
+- Didn't solve the problem (it was a config issue)
+</example>
+
+</balance>
+
+
+<decision_tree>
+```
+Is this a error message I don't recognize?
+├─ YES → Web search the error message
+└─ NO ↓
+
+Is this library/framework behavior I don't understand?
+├─ YES → Check docs (Context7 or official docs)
+└─ NO ↓
+
+Is this code I/my team wrote?
+├─ YES → Reason through it (logging, tracing, hypothesis testing)
+└─ NO ↓
+
+Is this a platform/environment difference?
+├─ YES → Research platform-specific behavior
+└─ NO ↓
+
+Can I observe the behavior directly?
+├─ YES → Add observability and reason through it
+└─ NO → Research the domain/concept first, then reason
+```
+</decision_tree>
+
+
+<red_flags>
+
+**You're researching too much if**:
+- You've read 20 blog posts but haven't looked at your code
+- You understand the theory but haven't traced your actual execution
+- You're learning about edge cases that don't apply to your situation
+- You've been reading for 30+ minutes without testing anything
+
+**You're reasoning too much if**:
+- You've been staring at code for an hour without progress
+- You keep finding things you don't understand and guessing
+- You're debugging library internals (that's research territory)
+- The error message is clearly from a library you don't know
+
+**You're doing it right if**:
+- You alternate between research and reasoning
+- Each research session answers a specific question
+- Each reasoning session tests a specific hypothesis
+- You're making steady progress toward understanding
+
+</red_flags>
+
+
+<mindset>
+
+**Good researchers ask**:
+- "What specific question do I need answered?"
+- "Where is the authoritative source for this?"
+- "Is this a known issue or unique to my code?"
+- "What version-specific information do I need?"
+
+**Good reasoners ask**:
+- "What is actually happening in my code?"
+- "What am I assuming that might be wrong?"
+- "How can I observe this behavior directly?"
+- "What experiment would test my hypothesis?"
+
+**Great debuggers do both**:
+- Research to fill knowledge gaps
+- Reason to understand actual behavior
+- Switch fluidly based on what they learn
+- Never stuck in one mode
+
+**The goal**: Minimum time to maximum understanding.
+- Research what you don't know
+- Reason through what you can observe
+- Fix what you understand
+</mindset>

package/src/resources/skills/frontend-design/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

package/src/resources/skills/swiftui/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: swiftui
+description: SwiftUI apps from scratch through App Store. Full lifecycle - create, debug, test, optimize, ship.
+---
+
+<essential_principles>
+## How We Work
+
+**The user is the product owner. Claude is the developer.**
+
+The user does not write code. The user does not read code. The user describes what they want and judges whether the result is acceptable. Claude implements, verifies, and reports outcomes.
+
+### 1. Prove, Don't Promise
+
+Never say "this should work." Prove it:
+```bash
+xcodebuild build 2>&1 | xcsift  # Build passes
+xcodebuild test                  # Tests pass
+open .../App.app                 # App launches
+```
+If you didn't run it, you don't know it works.
+
+### 2. Tests for Correctness, Eyes for Quality
+
+| Question | How to Answer |
+|----------|---------------|
+| Does the logic work? | Write test, see it pass |
+| Does it look right? | Launch app, user looks at it |
+| Does it feel right? | User uses it |
+| Does it crash? | Test + launch |
+| Is it fast enough? | Profiler |
+
+Tests verify *correctness*. The user verifies *desirability*.
+
+### 3. Report Outcomes, Not Code
+
+**Bad:** "I refactored the view model to use @Observable with environment injection"
+**Good:** "Fixed the state bug. App now updates correctly when you add items. Ready for you to verify."
+
+The user doesn't care what you changed. The user cares what's different.
+
+### 4. Small Steps, Always Verified
+
+```
+Change → Verify → Report → Next change
+```
+
+Never batch up work. Never say "I made several changes." Each change is verified before the next. If something breaks, you know exactly what caused it.
+
+### 5. Ask Before, Not After
+
+Unclear requirement? Ask now.
+Multiple valid approaches? Ask which.
+Scope creep? Ask if wanted.
+Big refactor needed? Ask permission.
+
+Wrong: Build for 30 minutes, then "is this what you wanted?"
+Right: "Before I start, does X mean Y or Z?"
+
+### 6. Always Leave It Working
+
+Every stopping point = working state. Tests pass, app launches, changes committed. The user can walk away anytime and come back to something that works.
+</essential_principles>
+
+<swiftui_principles>
+## SwiftUI Framework Principles
+
+### Declarative Mindset
+Describe what the UI should look like for a given state, not how to mutate it. Let SwiftUI manage the rendering. Never force updates - change the state and let the framework react.
+
+### Single Source of Truth
+Every piece of data has one authoritative location. Use the right property wrapper: @State for view-local, @Observable for shared objects, @Environment for app-wide. Derived data should be computed, not stored.
+
+### Composition Over Inheritance
+Build complex UIs by composing small, focused views. Extract reusable components when patterns emerge. Prefer many small views over few large ones.
+
+### Platform-Adaptive Design
+Write once but respect platform idioms. Use native navigation patterns, respect safe areas, adapt to screen sizes. Test on all target platforms.
+</swiftui_principles>
+
+<intake>
+**What would you like to do?**
+
+1. Build a new SwiftUI app
+2. Debug an existing SwiftUI app
+3. Add a feature to an existing app
+4. Write/run tests
+5. Optimize performance
+6. Ship/release to App Store
+7. Something else
+
+**Then read the matching workflow from `workflows/` and follow it.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "new", "create", "build", "start" | `workflows/build-new-app.md` |
+| 2, "broken", "fix", "debug", "crash", "bug" | `workflows/debug-swiftui.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", "app store" | `workflows/ship-app.md` |
+| 7, other | Clarify, then select workflow or references |
+</routing>
+
+<verification_loop>
+## After Every Change
+
+```bash
+# 1. Does it build?
+xcodebuild -scheme AppName build 2>&1 | xcsift
+
+# 2. Do tests pass? (use Core scheme for SwiftUI apps to avoid @main hang)
+xcodebuild -scheme AppNameCore test
+
+# 3. Does it launch?
+# macOS:
+open ./build/Build/Products/Debug/AppName.app
+
+# iOS Simulator:
+xcrun simctl boot "iPhone 15 Pro" 2>/dev/null || true
+xcrun simctl install booted ./build/Build/Products/Debug-iphonesimulator/AppName.app
+xcrun simctl launch booted com.yourcompany.appname
+```
+
+Note: If tests hang, the test target likely depends on the app target which has `@main`. Extract testable code to a framework target. See `../macos-apps/references/testing-tdd.md` for the pattern.
+
+Report to the user:
+- "Build: ✓"
+- "Tests: 12 pass, 0 fail"
+- "App launches, ready for you to check [specific thing]"
+</verification_loop>
+
+<cli_infrastructure>
+## CLI Workflow References
+
+For building, debugging, testing, and shipping from CLI without opening Xcode, read these from `../macos-apps/references/`:
+
+| Reference | Use For |
+|-----------|---------|
+| `cli-workflow.md` | Build, run, test commands; xcodebuild usage; code signing |
+| `cli-observability.md` | Log streaming, crash analysis, memory debugging, LLDB |
+| `project-scaffolding.md` | XcodeGen project.yml templates, file structure, entitlements |
+| `testing-tdd.md` | Test patterns that work from CLI, avoiding @main hangs |
+
+These docs are platform-agnostic. For iOS, change destinations:
+```bash
+# iOS Simulator
+xcodebuild -scheme AppName -destination 'platform=iOS Simulator,name=iPhone 15 Pro' build
+
+# macOS
+xcodebuild -scheme AppName build
+```
+</cli_infrastructure>
+
+<reference_index>
+## Domain Knowledge
+
+All in `references/`:
+
+**Core:**
+- architecture.md - MVVM patterns, project structure, dependency injection
+- state-management.md - Property wrappers, @Observable, data flow
+- layout-system.md - Stacks, grids, GeometryReader, custom layouts
+
+**Navigation & Animation:**
+- navigation.md - NavigationStack, sheets, tabs, deep linking
+- animations.md - Built-in animations, transitions, matchedGeometryEffect
+
+**Data & Platform:**
+- swiftdata.md - Persistence, @Model, @Query, CloudKit sync
+- platform-integration.md - iOS/macOS/watchOS/visionOS specifics
+- uikit-appkit-interop.md - UIViewRepresentable, hosting controllers
+
+**Support:**
+- networking-async.md - async/await, .task modifier, API clients
+- testing-debugging.md - Previews, unit tests, UI tests, debugging
+- performance.md - Profiling, lazy loading, view identity
+</reference_index>
+
+<workflows_index>
+## Workflows
+
+All in `workflows/`:
+
+| Workflow | Purpose |
+|----------|---------|
+| build-new-app.md | Create new SwiftUI app from scratch |
+| debug-swiftui.md | Find and fix SwiftUI bugs |
+| add-feature.md | Add functionality to existing app |
+| write-tests.md | Write UI and unit tests |
+| optimize-performance.md | Profile and improve performance |
+| ship-app.md | App Store submission, TestFlight, distribution |
+</workflows_index>
+
+<canonical_terminology>
+## Terminology
+
+Use these terms consistently:
+- **view** (not: widget, component, element)
+- **@Observable** (not: ObservableObject, @Published for new iOS 17+ code)
+- **NavigationStack** (not: NavigationView - deprecated)
+- **SwiftData** (not: Core Data for new projects)
+- **@Environment** (not: @EnvironmentObject for new code)
+- **modifier** (not: method/function when describing view modifiers)
+- **body** (not: render/build when describing view body)
+</canonical_terminology>