Miso Implementation Skill
Overview
This skill implements the miso feature-to-code workflow. When feature markdown files change, it automatically propagates those changes through the implementation chain: pseudocode → platform-specific code → product code.
Understanding Miso Features
Miso specifies programs as a tree of features: short (<300 word) natural-language markdown files that specify behavior.
Feature Format:
- Start with a
# title
- Followed by an emphasized one-line summary
- Up to 300 words of natural language
- Use simple language understandable by users
- Avoid technical jargon and code
Feature Structure:
Each feature lives in its own folder containing:
spec.md: The feature specification
pseudocode.md: Natural-language function definitions and patching instructions
ios.md, android.md, py.md: Platform-specific implementations with actual code
imp/: Folder for other artifacts (logs, debugging notes, test data)
Feature Hierarchy:
- To add detail to feature
A/spec.md, create subfeature A/B/spec.md
- To add detail to
A/B/spec.md, create subfeature A/B/C/spec.md
- Keep manageable: no more than 4-6 children per feature
- Group and summarize if children get out of control
The Implementation Process
When a user changes feature A/B/spec.md or adds a subfeature, the implementation process ensures code is created following this routine:
Step 1: Pseudocode
- Check if
A/B/pseudocode.md is up-to-date
- If not, ensure changes to the feature are reflected in pseudocode
- Pseudocode uses natural language function definitions
- Include patching instructions (where/how to integrate into product)
Step 2: Platform Code
- Check if platform implementations (
ios.md, android.md, etc.) are up-to-date vs pseudocode
- If not, edit them to reflect the most recent pseudocode changes
- Use platform-appropriate actual code syntax (Swift, Kotlin, Python)
Step 3: Product Code
- Check if actual target product code is up-to-date vs platform implementations
- If not, make appropriate modifications to product code
- Follow patching instructions from platform implementation files
Step 4: Build, Deploy, Test
- Build and deploy the changed feature to devices/servers
- Run tests if available
When to Use
Invoke this skill when the user:
- Says "implement features" or "run miso"
- Asks to "update implementations" or "sync code"
- Mentions implementing or deploying feature changes
- Wants to propagate feature changes to code
Implementation Workflow
The miso implementation process follows this sequence:
1. Detect Changed Features
Find all feature spec.md files that have changed since the last run:
- Use
git diff to find modified feature files in apps/ and miso/ directories
- Look for files matching pattern
**/spec.md
- Track the last run timestamp (stored in
.claude/skills/miso/.last-run)
2. Update Pseudocode
For each changed feature A/B/spec.md:
- Check if
A/B/pseudocode.md exists
- If it exists, read both the spec and pseudocode
- Determine if pseudocode needs updating based on spec changes
- If needed, update
A/B/pseudocode.md to reflect the spec changes
- Use natural language function definitions and patching instructions
3. Update Platform Implementations
For each feature with updated pseudocode:
- Check for platform-specific implementations:
A/B/ios.md, A/B/android.md, A/B/py.md
- For each existing platform file:
- Read the pseudocode and platform implementation
- Determine if platform code needs updating
- Update platform implementation to match pseudocode
- Use actual code syntax appropriate for the platform (Swift, Kotlin, Python)
4. Update Product Code
For each updated platform implementation:
- Identify the target product (look in
apps/ hierarchy to find the product path)
- Read the patching instructions from the platform implementation
- Locate the actual product code files that need modification
- Apply the changes to product code following the patching instructions
- Make minimal, targeted edits to existing code
5. Build, Deploy, and Test
After updating product code:
- Determine which platform was modified (iOS, Android, Python)
- Build and deploy using appropriate scripts:
- iOS:
./install-device.sh from product client imp/ios directory
- Android:
export JAVA_HOME="/opt/homebrew/opt/openjdk" && ./gradlew assembleDebug && adb install -r app/build/outputs/apk/debug/app-debug.apk
- Python:
./remote-shutdown.sh && scp && ssh for remote server deployment
- If a test exists for the feature, run it using
./test-feature.sh <feature-name>
6. Visual Verification and Iterative Debugging (for UI changes)
For features that affect visual appearance (colors, layouts, UI elements), use an iterative debugging cycle:
iOS Visual Verification Cycle:
Take Screenshot:
cd apps/firefly/product/client/imp/ios
./restart-app.sh
sleep 3
cd /Users/asnaroo/Desktop/experiments/miso/miso/platforms/ios/development/screen-capture/imp
./screenshot.sh /tmp/verification-screenshot.png
Verify Against Specification:
- Read the screenshot image
- Compare what you see to what the feature specification says
- For color changes: Check if expected color is visible
- For layout changes: Check if elements are positioned correctly
- For UI elements: Check if components appear as specified
If Verification PASSES:
- Proceed to step 7 (Update Implementation Documentation)
If Verification FAILS:
- Investigate: Search for ALL files that might contain the old implementation
- Example: For background color, search:
grep -r "Color(red: 64/255" NoobTest/
- Discovery: You may find the change is needed in multiple files, not just the ones initially updated
- Document findings: Note which files were missed
Fix All Instances:
- Update ALL files that need the change
- Rebuild:
./install-device.sh
- Restart:
./restart-app.sh && sleep 3
- Take another screenshot
- Read and verify again
Iterate Until Success:
- Repeat steps 4-5 until visual verification passes
- Don't stop at the first failed attempt
- Each failure teaches you about files that need updating
Android Visual Verification Cycle:
- Restart:
adb shell am force-stop com.miso.noobtest && adb shell am start -n com.miso.noobtest/.MainActivity
- Wait:
sleep 3
- Screenshot:
adb exec-out screencap -p > /tmp/verification-screenshot.png
- Read and verify (same logic as iOS)
- If fails: Search for missed files, fix, rebuild, repeat
Key Insight: Initial implementation often misses files. Visual verification catches this and drives iteration until the visible result matches the specification.
7. Post-Debug Cleanup
After visual verification succeeds and the feature works correctly, update all documentation to accurately reflect what was actually built. This is critical because the initial implementation often differs from the final working version due to debugging discoveries.
Run the post-debug cleanup process:
Review what was actually changed:
git diff apps/firefly/product/client/imp/ios/
Update the feature specification (spec.md):
- Ensure user-facing description matches final behavior
- Update visual details (exact colors, sizes, positions)
- Describe final gesture interactions (thresholds discovered during debugging)
- Keep <300 words, user-focused language
Update the pseudocode (pseudocode.md):
- Capture exact specifications discovered during debugging:
- Gesture thresholds (e.g., "30pt minimum for left swipe", "100pt for right swipe")
- UI measurements (e.g., "32pt icon with -8pt trailing padding")
- API endpoints with correct paths and response formats
- Visual specs (exact RGB values, font sizes, weights)
- Update patching instructions to reflect ALL files that need changes
- Include data structures that were added (e.g., new response types)
Update platform implementations (ios.md, android.md, etc.):
- Replace stub code with complete, working code from actual product files
- Include ALL target files that needed changes (discovered during debugging)
- Add exact file paths and line numbers
- Document any platform-specific workarounds (e.g.,
.highPriorityGesture for SwiftUI)
- Include complete API response structures with correct field names
Example Updates:
Feature spec (explore-posts/spec.md):
**Navigate to Children**: Swipe left on a post with children to navigate to a view showing all its child posts.
**Navigate Back**: Either tap the back button or swipe right anywhere in the child view to return to the parent view.
Pseudocode (explore-posts/pseudocode.md):
## Gesture Handling
**Swipe Left on Post with Children:**
- Minimum distance: 30pt
- Condition: Post must have children (childCount > 0)
**Swipe Right in Child View:**
- Minimum distance: 100pt
- Start position: Anywhere in view (not just left edge)
- Priority: High priority gesture to override ScrollView
Platform spec (explore-posts/ios.md):
// Complete working code with exact measurements
.gesture(
DragGesture(minimumDistance: 30)
.onEnded { value in
if value.translation.width < -30 && (post.childCount ?? 0) > 0 {
onNavigateToChildren?(post.id)
}
}
)
// In ChildPostsView - swipe right from anywhere
.highPriorityGesture(
DragGesture()
.onEnded { value in
if value.translation.width > 100 {
navigationPath.removeLast()
}
}
)
Why This Matters:
- Next time miso runs, the documentation will generate complete, working code immediately
- All debugging discoveries (exact thresholds, workarounds, edge cases) are preserved
- Another developer can implement the feature correctly from the docs
- If product code is deleted, specs can rebuild it without re-debugging
- The implementation documentation becomes an accurate, tested source of truth
State Tracking
Store the last run timestamp in .claude/skills/miso/.last-run:
- Before starting, read this file to get the baseline for comparison
- After successful completion, update it with the current timestamp
- If the file doesn't exist, compare against the last git commit
Key Principles
- Incremental: Only process features that have actually changed
- Chain of Trust: Each level (pseudocode → platform → product) builds on the previous
- Minimal Edits: Make targeted changes to existing code, don't rewrite unnecessarily
- Verify Visually: For UI changes, take screenshots and iterate until the result matches the spec
- Learn from Failures: Each visual verification failure reveals files that were missed
- Update Documentation: Capture all discovered changes in implementation files so next time is complete
- Track State: Remember what was last processed to avoid redundant work
Example Workflow
User modifies apps/firefly/features/background/spec.md (changes color from turquoise to mauve):
- Detect:
background/spec.md changed since last run
- Update Pseudocode:
apps/firefly/features/background/pseudocode.md to reflect mauve color
- Update Platform Spec:
apps/firefly/features/background/ios.md with new RGB values
- Update Product Code: Initial change to
ContentView.swift with RGB(224, 176, 255)
- Build & Deploy:
./install-device.sh
- Visual Verify (Attempt 1):
- Restart app, take screenshot
- FAILS: Still shows turquoise
- Investigation: App is showing PostsView, not ContentView!
- Fix & Rebuild:
- Update
PostsView.swift with mauve color
- Rebuild and redeploy
- Visual Verify (Attempt 2):
- Take screenshot again
- SUCCESS: Shows mauve background
- Search for Remaining Instances:
grep -r "Color(red: 64/255" NoobTest/
- Find 5 more files with old color
- Post-Debug Cleanup:
- Edit
background/spec.md: Describe grey/dark-red colors as user sees them
- Edit
background/pseudocode.md: Add exact RGB values (128,128,128) and (139,0,0)
- Edit
background/ios.md: List all 6 target files with line numbers and complete code examples
- Include search pattern: "Search for all instances of
Color(red: and replace..."
- Test: Run
./test-feature.sh background if test exists
- Track: Update
.last-run timestamp
Result: The documentation now accurately reflects the final implementation. All 6 files are documented with exact values. Next time miso runs, it will update all 6 files on the first attempt, with no debugging needed.
Important Notes
- Always read before writing - understand existing code structure
- Follow platform conventions (SwiftUI for iOS, Jetpack Compose for Android)
- Respect the JAVA_HOME requirement for Android builds
- Use LD="clang" for iOS builds to avoid Homebrew linker issues
- Check git status to understand what changed in the working directory
1---
2name: miso
3description: Implement feature changes by updating pseudocode, platform code, and product code from modified feature markdown files. Use when user asks to "implement features", "run miso", "update implementations", or "sync code with features".
4metadata:
5 source: https://skillmd.com/skills/majiayu000/miso
6---
7
8# Miso Implementation Skill
9
10## Overview
11
12This skill implements the miso feature-to-code workflow. When feature markdown files change, it automatically propagates those changes through the implementation chain: pseudocode → platform-specific code → product code.
13
14## Understanding Miso Features
15
16Miso specifies programs as a tree of **features**: short (<300 word) natural-language markdown files that specify behavior.
17
18**Feature Format**:
19- Start with a `#` title
20- Followed by an *emphasized* one-line summary
21- Up to 300 words of natural language
22- Use simple language understandable by users
23- Avoid technical jargon and code
24
25**Feature Structure**:
26Each feature lives in its own folder containing:
27- `spec.md`: The feature specification
28- `pseudocode.md`: Natural-language function definitions and patching instructions
29- `ios.md`, `android.md`, `py.md`: Platform-specific implementations with actual code
30- `imp/`: Folder for other artifacts (logs, debugging notes, test data)
31
32**Feature Hierarchy**:
33- To add detail to feature `A/spec.md`, create subfeature `A/B/spec.md`
34- To add detail to `A/B/spec.md`, create subfeature `A/B/C/spec.md`
35- Keep manageable: no more than 4-6 children per feature
36- Group and summarize if children get out of control
37
38## The Implementation Process
39
40When a user changes feature `A/B/spec.md` or adds a subfeature, the implementation process ensures code is created following this routine:
41
42**Step 1: Pseudocode**
43- Check if `A/B/pseudocode.md` is up-to-date
44- If not, ensure changes to the feature are reflected in pseudocode
45- Pseudocode uses natural language function definitions
46- Include patching instructions (where/how to integrate into product)
47
48**Step 2: Platform Code**
49- Check if platform implementations (`ios.md`, `android.md`, etc.) are up-to-date vs pseudocode
50- If not, edit them to reflect the most recent pseudocode changes
51- Use platform-appropriate actual code syntax (Swift, Kotlin, Python)
52
53**Step 3: Product Code**
54- Check if actual target product code is up-to-date vs platform implementations
55- If not, make appropriate modifications to product code
56- Follow patching instructions from platform implementation files
57
58**Step 4: Build, Deploy, Test**
59- Build and deploy the changed feature to devices/servers
60- Run tests if available
61
62## When to Use
63
64Invoke this skill when the user:
65- Says "implement features" or "run miso"
66- Asks to "update implementations" or "sync code"
67- Mentions implementing or deploying feature changes
68- Wants to propagate feature changes to code
69
70## Implementation Workflow
71
72The miso implementation process follows this sequence:
73
74### 1. Detect Changed Features
75
76Find all feature `spec.md` files that have changed since the last run:
77- Use `git diff` to find modified feature files in `apps/` and `miso/` directories
78- Look for files matching pattern `**/spec.md`
79- Track the last run timestamp (stored in `.claude/skills/miso/.last-run`)
80
81### 2. Update Pseudocode
82
83For each changed feature `A/B/spec.md`:
84- Check if `A/B/pseudocode.md` exists
85- If it exists, read both the spec and pseudocode
86- Determine if pseudocode needs updating based on spec changes
87- If needed, update `A/B/pseudocode.md` to reflect the spec changes
88- Use natural language function definitions and patching instructions
89
90### 3. Update Platform Implementations
91
92For each feature with updated pseudocode:
93- Check for platform-specific implementations: `A/B/ios.md`, `A/B/android.md`, `A/B/py.md`
94- For each existing platform file:
95 - Read the pseudocode and platform implementation
96 - Determine if platform code needs updating
97 - Update platform implementation to match pseudocode
98 - Use actual code syntax appropriate for the platform (Swift, Kotlin, Python)
99
100### 4. Update Product Code
101
102For each updated platform implementation:
103- Identify the target product (look in `apps/` hierarchy to find the product path)
104- Read the patching instructions from the platform implementation
105- Locate the actual product code files that need modification
106- Apply the changes to product code following the patching instructions
107- Make minimal, targeted edits to existing code
108
109### 5. Build, Deploy, and Test
110
111After updating product code:
112- Determine which platform was modified (iOS, Android, Python)
113- Build and deploy using appropriate scripts:
114 - iOS: `./install-device.sh` from product client imp/ios directory
115 - Android: `export JAVA_HOME="/opt/homebrew/opt/openjdk" && ./gradlew assembleDebug && adb install -r app/build/outputs/apk/debug/app-debug.apk`
116 - Python: `./remote-shutdown.sh && scp && ssh` for remote server deployment
117- If a test exists for the feature, run it using `./test-feature.sh <feature-name>`
118
119### 6. Visual Verification and Iterative Debugging (for UI changes)
120
121For features that affect visual appearance (colors, layouts, UI elements), use an **iterative debugging cycle**:
122
123**iOS Visual Verification Cycle**:
124
1251. **Take Screenshot**:
126 ```bash
127 cd apps/firefly/product/client/imp/ios
128 ./restart-app.sh
129 sleep 3
130 cd /Users/asnaroo/Desktop/experiments/miso/miso/platforms/ios/development/screen-capture/imp
131 ./screenshot.sh /tmp/verification-screenshot.png
132 ```
133
1342. **Verify Against Specification**:
135 - Read the screenshot image
136 - Compare what you see to what the feature specification says
137 - For color changes: Check if expected color is visible
138 - For layout changes: Check if elements are positioned correctly
139 - For UI elements: Check if components appear as specified
140
1413. **If Verification PASSES**:
142 - Proceed to step 7 (Update Implementation Documentation)
143
1444. **If Verification FAILS**:
145 - **Investigate**: Search for ALL files that might contain the old implementation
146 - **Example**: For background color, search: `grep -r "Color(red: 64/255" NoobTest/`
147 - **Discovery**: You may find the change is needed in multiple files, not just the ones initially updated
148 - **Document findings**: Note which files were missed
149
1505. **Fix All Instances**:
151 - Update ALL files that need the change
152 - Rebuild: `./install-device.sh`
153 - Restart: `./restart-app.sh && sleep 3`
154 - **Take another screenshot**
155 - Read and verify again
156
1576. **Iterate Until Success**:
158 - Repeat steps 4-5 until visual verification passes
159 - Don't stop at the first failed attempt
160 - Each failure teaches you about files that need updating
161
162**Android Visual Verification Cycle**:
1631. Restart: `adb shell am force-stop com.miso.noobtest && adb shell am start -n com.miso.noobtest/.MainActivity`
1642. Wait: `sleep 3`
1653. Screenshot: `adb exec-out screencap -p > /tmp/verification-screenshot.png`
1664. Read and verify (same logic as iOS)
1675. If fails: Search for missed files, fix, rebuild, repeat
168
169**Key Insight**: Initial implementation often misses files. Visual verification catches this and drives iteration until the visible result matches the specification.
170
171### 7. Post-Debug Cleanup
172
173After visual verification succeeds and the feature works correctly, **update all documentation to accurately reflect what was actually built**. This is critical because the initial implementation often differs from the final working version due to debugging discoveries.
174
175**Run the post-debug cleanup process:**
176
1771. **Review what was actually changed**:
178 ```bash
179 git diff apps/firefly/product/client/imp/ios/
180 ```
181
1822. **Update the feature specification** (`spec.md`):
183 - Ensure user-facing description matches final behavior
184 - Update visual details (exact colors, sizes, positions)
185 - Describe final gesture interactions (thresholds discovered during debugging)
186 - Keep <300 words, user-focused language
187
1883. **Update the pseudocode** (`pseudocode.md`):
189 - Capture exact specifications discovered during debugging:
190 - Gesture thresholds (e.g., "30pt minimum for left swipe", "100pt for right swipe")
191 - UI measurements (e.g., "32pt icon with -8pt trailing padding")
192 - API endpoints with correct paths and response formats
193 - Visual specs (exact RGB values, font sizes, weights)
194 - Update patching instructions to reflect ALL files that need changes
195 - Include data structures that were added (e.g., new response types)
196
1974. **Update platform implementations** (`ios.md`, `android.md`, etc.):
198 - Replace stub code with complete, working code from actual product files
199 - Include ALL target files that needed changes (discovered during debugging)
200 - Add exact file paths and line numbers
201 - Document any platform-specific workarounds (e.g., `.highPriorityGesture` for SwiftUI)
202 - Include complete API response structures with correct field names
203
2045. **Example Updates**:
205
206 **Feature spec (`explore-posts/spec.md`)**:
207 ```markdown
208 **Navigate to Children**: Swipe left on a post with children to navigate to a view showing all its child posts.
209
210 **Navigate Back**: Either tap the back button or swipe right anywhere in the child view to return to the parent view.
211 ```
212
213 **Pseudocode (`explore-posts/pseudocode.md`)**:
214 ```markdown
215 ## Gesture Handling
216
217 **Swipe Left on Post with Children:**
218 - Minimum distance: 30pt
219 - Condition: Post must have children (childCount > 0)
220
221 **Swipe Right in Child View:**
222 - Minimum distance: 100pt
223 - Start position: Anywhere in view (not just left edge)
224 - Priority: High priority gesture to override ScrollView
225 ```
226
227 **Platform spec (`explore-posts/ios.md`)**:
228 ```swift
229 // Complete working code with exact measurements
230 .gesture(
231 DragGesture(minimumDistance: 30)
232 .onEnded { value in
233 if value.translation.width < -30 && (post.childCount ?? 0) > 0 {
234 onNavigateToChildren?(post.id)
235 }
236 }
237 )
238
239 // In ChildPostsView - swipe right from anywhere
240 .highPriorityGesture(
241 DragGesture()
242 .onEnded { value in
243 if value.translation.width > 100 {
244 navigationPath.removeLast()
245 }
246 }
247 )
248 ```
249
2506. **Why This Matters**:
251 - Next time miso runs, the documentation will generate complete, working code immediately
252 - All debugging discoveries (exact thresholds, workarounds, edge cases) are preserved
253 - Another developer can implement the feature correctly from the docs
254 - If product code is deleted, specs can rebuild it without re-debugging
255 - The implementation documentation becomes an accurate, tested source of truth
256
257## State Tracking
258
259Store the last run timestamp in `.claude/skills/miso/.last-run`:
260- Before starting, read this file to get the baseline for comparison
261- After successful completion, update it with the current timestamp
262- If the file doesn't exist, compare against the last git commit
263
264## Key Principles
265
2661. **Incremental**: Only process features that have actually changed
2672. **Chain of Trust**: Each level (pseudocode → platform → product) builds on the previous
2683. **Minimal Edits**: Make targeted changes to existing code, don't rewrite unnecessarily
2694. **Verify Visually**: For UI changes, take screenshots and iterate until the result matches the spec
2705. **Learn from Failures**: Each visual verification failure reveals files that were missed
2716. **Update Documentation**: Capture all discovered changes in implementation files so next time is complete
2727. **Track State**: Remember what was last processed to avoid redundant work
273
274## Example Workflow
275
276User modifies `apps/firefly/features/background/spec.md` (changes color from turquoise to mauve):
277
2781. **Detect**: `background/spec.md` changed since last run
2792. **Update Pseudocode**: `apps/firefly/features/background/pseudocode.md` to reflect mauve color
2803. **Update Platform Spec**: `apps/firefly/features/background/ios.md` with new RGB values
2814. **Update Product Code**: Initial change to `ContentView.swift` with RGB(224, 176, 255)
2825. **Build & Deploy**: `./install-device.sh`
2836. **Visual Verify (Attempt 1)**:
284 - Restart app, take screenshot
285 - **FAILS**: Still shows turquoise
286 - Investigation: App is showing PostsView, not ContentView!
2877. **Fix & Rebuild**:
288 - Update `PostsView.swift` with mauve color
289 - Rebuild and redeploy
2908. **Visual Verify (Attempt 2)**:
291 - Take screenshot again
292 - **SUCCESS**: Shows mauve background
2939. **Search for Remaining Instances**:
294 - `grep -r "Color(red: 64/255" NoobTest/`
295 - Find 5 more files with old color
29610. **Post-Debug Cleanup**:
297 - Edit `background/spec.md`: Describe grey/dark-red colors as user sees them
298 - Edit `background/pseudocode.md`: Add exact RGB values (128,128,128) and (139,0,0)
299 - Edit `background/ios.md`: List all 6 target files with line numbers and complete code examples
300 - Include search pattern: "Search for all instances of `Color(red:` and replace..."
30111. **Test**: Run `./test-feature.sh background` if test exists
30212. **Track**: Update `.last-run` timestamp
303
304**Result**: The documentation now accurately reflects the final implementation. All 6 files are documented with exact values. Next time miso runs, it will update all 6 files on the first attempt, with no debugging needed.
305
306## Important Notes
307
308- Always read before writing - understand existing code structure
309- Follow platform conventions (SwiftUI for iOS, Jetpack Compose for Android)
310- Respect the JAVA_HOME requirement for Android builds
311- Use LD="clang" for iOS builds to avoid Homebrew linker issues
312- Check git status to understand what changed in the working directory