Speak Local Dev Loop
Developmentspeak-local-dev-loopSpeak Local Dev Loop is an Agent Skill for development published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Configure Speak local development with mocked tutors and audio testing. Use when setting up a development environment, configuring test workflows, or building language learning features locally. Trigger with phrases like "speak dev setup", "speak local development", "speak dev environment", "develop with speak".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/speak-pack/skills/speak-local-dev-loop/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/speak-local-dev-loop, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Speak Local Dev Loop
Overview
Set up a fast local development workflow for Speak language learning integrations. Includes mock tutor responses for offline development, audio test fixtures, and a debug mode for scoring analysis.
Prerequisites
- Completed
speak-install-authsetup - Node.js 18+ with npm/pnpm
- ffmpeg installed (for audio conversion)
Instructions
Step 1: Project Structure
speak-app/
src/
speak/client.ts # Speak API client
speak/tutor.ts # AI tutor conversation manager
speak/pronunciation.ts # Pronunciation assessment
speak/audio.ts # Audio recording and preprocessing
tests/
mocks/ # Mock responses for offline dev
fixtures/ # Sample audio files for testing
unit/ # Unit tests with mocked API
integration/ # Integration tests (needs API key)
.env.development # Dev credentials
.env.test # Test credentials (mock mode)
Step 2: Mock Tutor for Offline Development
// tests/mocks/mock-speak-client.ts
export class MockSpeakClient {
async startConversation(config: any) {
return {
id: 'mock-session-123',
firstPrompt: {
text: 'Hola! Bienvenido. Como te llamas?',
audioUrl: null,
},
};
}
async sendTurn(sessionId: string, input: any) {
return {
tutorText: 'Muy bien! Tu pronunciacion es buena.',
pronunciationScore: 85,
corrections: [],
vocabularyNotes: ['llamo = I call myself'],
};
}
async assessPronunciation(config: any) {
return {
score: 82,
words: [
{ text: 'Hola', score: 95, phonemes: [] },
{ text: 'como', score: 78, phonemes: [
{ symbol: 'o', score: 65, suggestion: 'Round lips more' }
]},
],
};
}
}
Step 3: Audio Test Fixtures
# Generate test audio files using text-to-speech
# macOS:
say -v "Paulina" "Hola, como estas" -o tests/fixtures/hola-es.wav
# Linux:
espeak -v es "Hola, como estas" -w tests/fixtures/hola-es.wav
# Convert to required format
ffmpeg -i tests/fixtures/hola-es.wav -ar 16000 -ac 1 tests/fixtures/hola-es-16k.wav
Step 4: Development Scripts
{
"scripts": {
"dev": "tsx watch src/index.ts",
"dev:mock": "SPEAK_MOCK_MODE=true tsx watch src/index.ts",
"test": "vitest run",
"test:watch": "vitest",
"lesson:test": "tsx src/test-lesson.ts"
}
}
Step 5: Debug Mode
// Enable detailed scoring output
const DEBUG = process.env.SPEAK_DEBUG === 'true';
function logAssessment(result: PronunciationResult) {
if (!DEBUG) return;
console.log('=== Pronunciation Debug ===');
for (const word of result.words) {
const flag = word.score < 70 ? 'WEAK' : 'OK';
console.log(` [${flag}] "${word.text}": ${word.score}/100`);
for (const p of word.phonemes || []) {
if (p.score < 70) {
console.log(` phoneme "${p.symbol}": ${p.score} - ${p.suggestion}`);
}
}
}
}
Output
- Project structure with client, tests, and mocks
- Mock tutor client for offline development
- Audio test fixtures generated with TTS
- Debug mode for pronunciation analysis
- Development scripts for fast iteration
Error Handling
| Error | Cause | Solution |
|---|---|---|
| ffmpeg not found | Not installed | Install via brew install ffmpeg or apt install ffmpeg |
| Mock mode not activating | Env var not set | Check SPEAK_MOCK_MODE=true |
| Audio file too large | Long recording | Trim to 30 seconds max for testing |
| Test timeout | Slow API response | Use mock mode for unit tests |
Resources
Next Steps
See speak-sdk-patterns for production-ready code patterns.
Examples
Mock-first development: Run npm run dev:mock to iterate on UI and conversation flow without API calls. Switch to real API for integration testing.
Audio quality testing: Record samples at different quality levels and compare pronunciation scores to calibrate your recording pipeline.