MQTT + Ollama Home Automation Assistant

Expert assistant for the CodeMash 2.0.0.6 presentation project demonstrating local AI-powered home automation using Next.js, LangChain.js, Ollama, MQTT, Z-Wave devices, and Auth0.

What This Skill Does

This skill provides specialized guidance for working on a multi-module presentation project that showcases local-first AI home automation. It enforces critical project constraints (JavaScript-only, no TypeScript; never run server commands) and ensures proper task tracking, documentation updates, and git workflow compliance.

Project Structure

The project has three main applications:

All documentation lives in `docs/`, and change proposals use OpenSpec format in `openspec/`.

Instructions

CRITICAL CONSTRAINTS

1. **JavaScript Only - NEVER Use TypeScript**

- FORBIDDEN: `.ts`, `.tsx` files, type annotations, TypeScript syntax

- REQUIRED: `.js`, `.jsx` files, plain ES6+ JavaScript

- Use JSDoc for documentation only (optional)

- This is a converted project - respect the JavaScript-only constraint

2. **Never Run Server Commands**

- DO NOT execute: `npm run dev`, `npm start`, `next dev`, `node server.js`, or any long-running process

- User runs servers manually in their own terminal

- ALLOWED: `npm install`, `npm run build`, `npm test`, `npm run lint`, one-time scripts

3. **Local-First Architecture**

- Minimize cloud dependencies

- All AI processing, device control, and data storage should happen locally

- Document any network dependencies in `docs/network-dependencies.md` with rationale and fallback plans

- Principle: Local processing > Cloud, Offline-capable > Internet-required, Demo reliability > Feature complexity

Task Management Workflow

1. **For New Features/Changes:**

- Check if `openspec/AGENTS.md` exists

- If yes, follow OpenSpec workflow for proposals and specs

- If no, proceed with direct implementation

2. **Always Update Task Tracking:**

- Edit `docs/tasks.md` after completing any task

- Use status indicators: ⏳ Not Started, 🔄 In Progress, ✅ Completed

- This is MANDATORY for every code change

3. **Keep Documentation in Sync:**

When making changes, update relevant docs:

- `README.md` - User-facing changes

- `docs/TECH-STACK.md` - Technology changes

- `docs/EXTERNAL-INTEGRATIONS.md` - Integration changes

- `docs/DEPLOYMENT.md` - Deployment changes

- `docs/tasks.md` - ALWAYS update for completed tasks

- `docs/network-dependencies.md` - New network dependencies

Git Workflow

1. **Never commit to `main`** - Always create feature branches:

```bash

git checkout -b feature/descriptive-name

```

2. **Use conventional commits:**

- `feat:` - New feature

- `fix:` - Bug fix

- `docs:` - Documentation changes

- `test:` - Test additions/changes

- `refactor:` - Code refactoring

- `chore:` - Maintenance tasks

3. **Commit and push:**

```bash

git add .

git commit -m "feat: your descriptive message"

git push -u origin feature/descriptive-name

```

4. User will merge via PR - don't merge yourself

Voice Gateway Demo Modes

The voice gateway supports 4 configuration-driven demo modes with independent AI and TTS provider selection:

**Important:**

Z-Wave MQTT Integration

**CRITICAL:** Never change the Z-Wave MQTT topic format:

```

zwave/[Location/]Device_Name/command_class/endpoint_0/targetValue/set

```

This format is dictated by the Z-Wave JS UI MQTT gateway and must not be modified. See `docs/EXTERNAL-INTEGRATIONS.md` for details.

Pre-Commit Checklist

Before committing, verify:

Pre-Deployment Checklist

Before deployment:

Key Files Reference

**AI Guidelines:**

**Developer Docs:**

**Troubleshooting:**

**Module READMEs:**

Quick Commands Reference

**Installation:**

```bash

npm install # From project root or module directory

```

**Testing:**

```bash

npm test # Run tests

npm run lint # Check code style

```

**Building:**

```bash

npm run build # Build for production

```

**Deployment Logs:**

```bash

journalctl -u oracle.service -f

journalctl -u voice-gateway-oww.service -f

```

Example Usage

**Scenario 1: Adding a new voice command**

1. Read `apps/voice-gateway-oww/README.md` for architecture

2. Create feature branch: `git checkout -b feature/add-brightness-command`

3. Implement command handler in JavaScript (no TypeScript!)

4. Add tests, run `npm test`

5. Update `docs/tasks.md` marking task as ✅ Completed

6. Update `README.md` with new command documentation

7. Commit: `git commit -m "feat: add brightness control voice command"`

8. Push: `git push -u origin feature/add-brightness-command`

**Scenario 2: Troubleshooting voice gateway**

1. Check `docs/voice-gateway-troubleshooting.md`

2. Check logs: `journalctl -u voice-gateway-oww.service -f`

3. Verify `.env` file has correct `AI_PROVIDER` and `TTS_PROVIDER` values

4. Confirm Ollama models are downloaded (if using Ollama)

5. Test MQTT connection separately

**Scenario 3: Updating Z-Wave device integration**

1. Read `docs/EXTERNAL-INTEGRATIONS.md` Z-Wave section

2. CRITICAL: Do NOT modify MQTT topic format

3. Create feature branch

4. Modify device mappings in JavaScript

5. Test with real hardware

6. Update `docs/EXTERNAL-INTEGRATIONS.md` if device config changed

7. Update `docs/tasks.md`

8. Commit with conventional commit message

Important Notes