# DuckLM Runtime Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the first runnable DuckLM local cognitive runtime from `Ducklm.md`.

**Architecture:** FastAPI exposes WebChat and HTTP endpoints, RuntimeLoop coordinates tasks, ModelClient calls an OpenAI-compatible `llama-server`, and SQLite persists tasks/events/approvals/experience. Tools, skills, and memory are small adapters with clear boundaries so later stages can grow without turning the runtime into hardcoded workflow rules.

**Tech Stack:** Python 3.11+, FastAPI, httpx, aiosqlite, Pydantic, Jinja2, PyYAML, jsonschema, Qdrant client.

---

### Task 1: Tests First

**Files:**
- Create: `tests/smoke/test_models_config.py`
- Create: `tests/smoke/test_model_client.py`
- Create: `tests/smoke/test_api_health.py`
- Create: `tests/smoke/test_event_log.py`
- Create: `tests/smoke/test_action_directive_schema.py`
- Create: `tests/smoke/test_tool_gateway.py`
- Create: `tests/smoke/test_approvals.py`
- Create: `tests/smoke/test_skill_registry.py`
- Create: `tests/smoke/test_experience_recorder.py`
- Create: `tests/smoke/test_vector_memory.py`

- [ ] Write smoke tests for config, model role mapping, stores, tools, approvals, skills, experience, memory, and API health.
- [ ] Run `python -m pytest tests/smoke -v` and verify tests fail because implementation modules do not exist.

### Task 2: Runtime Core

**Files:**
- Create: `pyproject.toml`
- Create: `.env.example`
- Create: `config/models.yaml`
- Create: `duck_core/config.py`
- Create: `duck_core/model_client.py`
- Create: `duck_core/events/store.py`
- Create: `duck_core/tasks/store.py`
- Create: `duck_core/tasks/state.py`
- Create: `duck_core/context_builder.py`
- Create: `duck_core/runtime_loop.py`
- Create: `duck_core/api.py`

- [ ] Implement settings and model config loading.
- [ ] Implement ModelClient role-based chat calls with latency and usage capture.
- [ ] Implement SQLite task and event stores.
- [ ] Implement RuntimeLoop for `POST /v1/chat`.
- [ ] Implement FastAPI endpoints and WebChat rendering.

### Task 3: Stage Adapters

**Files:**
- Create: `duck_core/tools/*`
- Create: `duck_core/approvals/service.py`
- Create: `duck_core/skills/registry.py`
- Create: `duck_core/experience/recorder.py`
- Create: `duck_core/reflection.py`
- Create: `duck_core/memory/*`
- Create: `duck_core/schemas/action_directive.schema.json`

- [ ] Implement safe file read/write and allowlisted shell execution.
- [ ] Implement exact-action approval records.
- [ ] Implement filesystem SkillRegistry.
- [ ] Implement experience recording and skill proposal writing.
- [ ] Implement Qdrant memory adapter with explicit embedding-disabled errors.

### Task 4: Project Surface

**Files:**
- Create: `scripts/llama/*`
- Create: `scripts/verify/*`
- Create: `scripts/bench/bench_runtime.py`
- Create: `duck_core/web/templates/*`
- Create: `duck_core/web/static/*`
- Create: `skills/analyze_project/*`
- Create: `docker-compose.memory.yml`
- Create: `Makefile`
- Create: `README.md`
- Create: `docs/*.md`

- [ ] Add llama-server scripts, verification scripts, benchmark, WebChat pages, starter skill, compose file, make targets, and docs.
- [ ] Run smoke tests and syntax checks.