hyochan · hyochan · Apr 25, 2026 · Apr 15, 2026 · Apr 15, 2026 · Apr 15, 2026
diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md
@@ -0,0 +1,220 @@
+# Commit Changes
+
+Complete workflow: branch → commit → push → PR, for `hyochan/react-native-nitro-sound`.
+
+## Usage
+
+```text
+/commit [options]
+```
+
+**Options:**
+
+- `--push` / `-p`: Push to remote after commit
+- `--pr`: Create PR after push
+- `--all` / `-a`: Commit all changes at once
+- `<path>`: Commit only specific path (e.g., `ios/`, `android/`, `src/`)
+
+## Examples
+
+```bash
+/commit src/ --pr
+/commit --all --pr
+/commit ios/
+```
+
+## Complete Workflow
+
+### 1. Check Branch
+
+```bash
+git branch --show-current
+```
+
+If on `main` → create a feature branch first:
+
+```bash
+git checkout -b <type>/<scope>-<short-description>
+```
+
+**Branch naming:**
+
+- `feat/<scope>-<feature>` — new feature
+- `fix/<scope>-<bug>` — bug fix
+- `docs/<scope>-<update>` — docs only
+- `chore/<scope>-<task>` — deps, tooling, refactor
+
+**Scopes** (match commit scopes below).
+
+### 2. Check Current Status
+
+```bash
+git status
+git diff --name-only
+```
+
+### 3. Stage Changes
+
+**Specific path:**
+
+```bash
+git add <path>
+```
+
+**All:**
+
+```bash
+git add .
+```
+
+### 4. Review Staged Changes
+
+```bash
+git diff --cached --stat
+```
+
+### 5. Create Commit
+
+Conventional commit format:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<type>(<scope>): <description>
+
+<body — what changed and why>
+
+🤖 Autogenerated by Claude (AI-native maintenance).
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Types:**
+
+| Type       | Description                  |
+| ---------- | ---------------------------- |
+| `feat`     | New feature                  |
+| `fix`      | Bug fix                      |
+| `docs`     | Documentation                |
+| `refactor` | Code refactor                |
+| `chore`    | Maintenance / deps           |
+| `test`     | Tests                        |
+| `ci`       | CI / GitHub Actions          |
+| `perf`     | Performance                  |
+
+**Scopes:**
+
+- `ios` — `ios/` Swift
+- `android` — `android/` Kotlin
+- `ts` / `js` — TypeScript in `src/`
+- `nitro` — `*.nitro.ts` specs or nitrogen-generated code
+- `example` — `example/`
+- `deps` — dependency bumps
+- `ci` — `.github/`
+- `skills` — `.claude/commands/`
+
+### 6. Push to Remote
+
+```bash
+git push -u origin <branch-name>
+```
+
+### 7. Create Pull Request
+
+```bash
+gh pr create --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points>
+
+## Changes
+- <change 1>
+- <change 2>
+
+## Test plan
+- [ ] `yarn typecheck` passes
+- [ ] `yarn lint` passes
+- [ ] iOS example builds
+- [ ] Android example builds
+
+🤖 Autogenerated by Claude (AI-native maintenance).
+EOF
+)"
+```
+
+### 8. Add Labels
+
+```bash
+gh label list --repo hyochan/react-native-nitro-sound
+gh pr edit <PR_NUMBER> --add-label "<label1>,<label2>"
+```
+
+**Label guide:**
+
+- Changes under `ios/` → `📱 iOS`
+- Changes under `android/` → `🤖 android`
+- Changes under `src/` crossing both platforms → `cross-platform`
+- Dep bumps → `dependencies`
+- `.github/` → `💨 ci`
+- New features → `🍗 enhancement`
+- Bug fixes → `🐛 bug`
+- Refactors → `🝤 refactor`
+- Docs → `📖 documentation`
+- Breaking → `⚡️ breaking`
+
+---
+
+## Commit Order (for cross-stack changes)
+
+When touching multiple layers, commit in this order so reviewers can follow:
+
+| Order | Path                  | Description                                    |
+| ----- | --------------------- | ---------------------------------------------- |
+| 1     | `src/specs/*.nitro.ts`| Nitro spec changes (API surface)               |
+| 2     | `nitrogen/generated/` | Regenerated nitrogen code                      |
+| 3     | `ios/`                | iOS implementation                             |
+| 4     | `android/`            | Android implementation                         |
+| 5     | `src/` (non-spec)     | JS / TS wrapper                                |
+| 6     | `example/`            | Example app updates                            |
+| 7     | `docs/` / `README.md` | Documentation                                  |
+| 8     | `.claude/commands/`   | Skill updates                                  |
+
+---
+
+## Example Commits
+
+**Nitro spec change:**
+
+```
+feat(nitro): add segmented recording API
+
+- Add RecordingSegmentConfig to Sound.nitro.ts
+- Introduce startRecorderSegmented() method
+
+🤖 Autogenerated by Claude (AI-native maintenance).
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**iOS fix:**
+
+```
+fix(ios): prevent crash on corrupted std::optional<double>
+
+When an upstream caller passes a malformed Double, the bridge now
+coerces via a safe NaN/inf check before Int conversion.
+
+Closes #774
+
+🤖 Autogenerated by Claude (AI-native maintenance).
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**Dep bump:**
+
+```
+chore(deps): bump react-native-nitro-modules to 0.35.4
+
+Minor patch release. No API changes.
+
+🤖 Autogenerated by Claude (AI-native maintenance).
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
diff --git a/.claude/commands/compile-knowledge.md b/.claude/commands/compile-knowledge.md
@@ -0,0 +1,118 @@
+# Compile Knowledge Base
+
+Regenerate AI context files for `react-native-nitro-sound` so Claude (and other AI assistants) have an up-to-date, compact reference when working on this repo.
+
+> This repo is AI-native: Claude maintains it. That means the knowledge base IS the contract. Keep it fresh.
+
+## Output Files
+
+| Output           | Location                     | Purpose                                       |
+| ---------------- | ---------------------------- | --------------------------------------------- |
+| `context.md`     | `knowledge/_claude-context/` | Claude Code context for this repo             |
+| `llms.txt`       | `docs/public/` (if site)     | AI assistant quick reference                  |
+| `llms-full.txt`  | `docs/public/` (if site)     | AI assistant full reference                   |
+
+If there is no docs site yet, only `knowledge/_claude-context/context.md` is required.
+
+## When to Run
+
+- After changing any `*.nitro.ts` spec in `src/specs/`
+- After upgrading `react-native-nitro-modules` or `nitrogen`
+- After non-trivial changes in `ios/` or `android/` native layers
+- After README or API surface changes
+- Before cutting a release
+
+## Compile Steps
+
+### 1. Collect Sources
+
+Read, in this order:
+
+1. `README.md` — user-facing API overview
+2. `src/specs/*.nitro.ts` — the Nitro spec (source of truth for the native API)
+3. `src/index.ts` and `src/*.ts` — TypeScript wrapper
+4. `ios/*.swift` — iOS implementation notes
+5. `android/src/main/java/**/*.kt` — Android implementation notes
+6. `package.json` — current versions (nitro-modules, RN peer range)
+7. `CHANGELOG.md` — recent changes
+
+### 2. Generate `context.md`
+
+Write to `knowledge/_claude-context/context.md` with these sections:
+
+```markdown
+# react-native-nitro-sound — AI Context
+
+> Autogenerated. Do not edit by hand. Run `/compile-knowledge`.
+
+## Repo Purpose
+<1-paragraph summary>
+
+## Architecture
+- Built on `react-native-nitro-modules` (Nitro)
+- iOS: AVAudioRecorder + AVAudioPlayer under Swift
+- Android: MediaRecorder + MediaPlayer under Kotlin
+- Spec-first: `src/specs/*.nitro.ts` → nitrogen → native bindings
+
+## Current Versions
+- Library: <x.y.z>
+- Peer: react-native-nitro-modules >= <x.y.z>
+- React Native tested against: <x.y>
+- Nitrogen: <x.y.z>
+
+## Public API
+<Enumerate from src/index.ts — one line per export>
+
+## Nitro Spec Surface
+<Methods / properties from *.nitro.ts — signature only>
+
+## Platform Notes
+### iOS
+<Key behaviors, known pitfalls (e.g. Release build codec handling, std::optional<double> coercion)>
+
+### Android
+<Key behaviors, foreground service, ndkVersion requirement, 16KB page size status>
+
+## Known Issue Classes
+- Legacy bugs from `react-native-audio-recorder-player` (pre-Nitro) → label `🗑 stale-legacy`
+- Build failures on RN 0.81+ → track nitro-modules compatibility
+- iOS Release-only codec issues → check AudioSet patch history
+
+## Release / Maintenance
+- Autogenerated commits & PRs by Claude (AI-native)
+- Hyo triages direction; mobile triggers via `/ai triage` on an issue → dispatches workflow
+
+## Key Files
+- `src/specs/Sound.nitro.ts`
+- `src/index.ts`
+- `ios/HybridSound.swift`
+- `android/src/main/java/com/margelo/nitro/sound/HybridSound.kt`
- `ios/HybridSound.swift`
- `android/src/main/java/com/margelo/nitro/sound/HybridSound.kt`
+- `ios/Sound.swift` 
+- `android/src/main/java/com/margelo/nitro/audiorecorderplayer/Sound.kt` 
- `ios/HybridSound.swift`
- `android/src/main/java/com/margelo/nitro/sound/HybridSound.kt`
+- `ios/Sound.swift` 
+- `android/src/main/java/com/margelo/nitro/audiorecorderplayer/Sound.kt` 
+- `.claude/commands/*.md` — AI-native workflow skills
+```
+
+### 3. (Optional) Generate `llms.txt` / `llms-full.txt`
+
+Only if a docs site is present under `docs/`.
+
+- `llms.txt` — 1 page: project summary, install command, peer deps, top-level API with 1-line descriptions
+- `llms-full.txt` — full concatenation of public docs + API signatures
+
+### 4. Commit
+
+```bash
+git add knowledge/_claude-context/context.md
+# if generated:
+git add docs/public/llms.txt docs/public/llms-full.txt
+git commit -m "docs: recompile knowledge base
+
+🤖 Autogenerated by Claude (AI-native maintenance).
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+## SST (Single Source of Truth)
+
+```text
+src/specs/*.nitro.ts  ──┐
+README.md             ──┤
+ios/ + android/       ──┴──► /compile-knowledge ──► knowledge/_claude-context/context.md
+```